Skip to content

Commit

Permalink
Update README to be more clear about new posts
Browse files Browse the repository at this point in the history
Clarify expected directory structure, file naming
Add example of blog post metadata
  • Loading branch information
Tracey Clark committed Oct 2, 2023
1 parent 1a22217 commit 610bab6
Showing 1 changed file with 58 additions and 6 deletions.
64 changes: 58 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Solus Site

Static, [Hugo-based](https://gohugo.io) home of Solus and its projects. This website makes used of:
Static, [Hugo-based](https://gohugo.io) home of Solus and its projects. This website makes use of:

1. A custom theme, [`solus-hugo-theme`](https://github.com/getsolus/solus-hugo-theme).
2. Website content itself, including blog posts, in `content`.
Expand All @@ -11,20 +11,72 @@ Static, [Hugo-based](https://gohugo.io) home of Solus and its projects. This web

### New Post

To create a new post, call `hugo new PATH`. For instance, `hugo new blog/2023/02/welcome-to-the-new-site.md` would create `2023/02/welcome-to-the-new-site.md` with our default
configuration in the `content/blog/` directory.
To create a new post, change to the main directory of this repo (solus-site.github.io).
From there, call `hugo new PATH`. The `PATH` format is `blog/year/month/post-title/post-title.md`.

For instance, to create a blog post for Feb. 2023 with the name "Welcome To The New Site", you would use: `hugo new blog/2023/02/welcome-to-the-new-site/welcome-to-the-new-site.md`.
This would create `content/blog2023/02/welcome-to-the-new-site/welcome-to-the-new-site.md`.

The markdown file will be created with our default configuration, which you can update as necessary. For metadata, most fields are self-explanatory.

- "name" - should match the name for your data file under `data/team/name.yml` (required)
- "featuredimage" - a relative link to an image such as "/image.png" (optional)
- "categories" is set to "news" by default. You can optionally add others.

Any featured image file must be in the same directory as the blog post.

### File and directory standards

Each year has a directory, with subdirectories for each month which has content.
Each post has a directory under the appropriate month. The directory and filename are the title of the post. (It's also OK to name the markdown file `index.md` but then you'll have to manually edit the title).
As an example, as of October, the directory for 2023 looks like:

```
2023
├── 04
│ └── a-new-voyage
│ ├── featured-image.jpg
│ └── index.md
├── 07
│ └── solus-4-4-released
│ ├── index.md
│ └── solus-4.4-featured.jpg
├── 08
│ └── state-of-solus-august-2023
│ ├── index.md
│ └── StateOfSolusAugust2023.jpg
└── 10
└── solus-and-hacktoberfest-2023
├── hf10_horz_fcd_rgb.png
└── index.md
```

Example of blog post metadata

```
---
title: "Solus 4.4 Released"
author: "joshua"
categories:
- news
- releases
date: 2023-07-08T00:27:44+03:00
featuredimage: "/solus-4.4-featured.jpg"
url: "/2023/07/08/solus-4-4-released"
---
```

## Development

### Setup

To set up your Solus system for the website development, you first need to ensure you have the necessary dependencies installed. Run `make setup` to install the necessary dependencies as well as init git submodules.
To set up your Solus system for developing the website, you first need to ensure you have the necessary dependencies installed. Run `make setup` to install the necessary dependencies as well as init git submodules.

Next, run `make sync` to update the Hugo themes.

### Local Server

You can start up a local server by calling `make local` in the `solus-site` directory. This will expose the site on `http://127.0.0.1:1313`.
You can start up a local server by calling `make local` in the `solus-site` directory. This will expose the site on `http://127.0.0.1:1313`. Use this to see your changes and make sure things look as you expect before submitting a pull request.

**Note:** You will not need to restart the server when doing changes. Hugo does file watching across all the things.

Expand All @@ -34,7 +86,7 @@ Merge the `main` branch into `deploy` and push.

### Styling

I use 4-char wide tabs, not spaces, in everything **except** the YAML files, which use 4 spaces. Sorry!
We use 4-char wide tabs, not spaces, in everything **except** the YAML files, which use 4 spaces. Sorry!

## Licensing

Expand Down

0 comments on commit 610bab6

Please sign in to comment.