CCCHH/ccchh-website
CCCHH/ccchh-website
3
3
Fork 4
Code Issues 5 Pull requests 10 Activity Actions 2

Better explain content types #165

Merged
stb merged 1 commit from explain-content-types into main 2026-06-14 21:20:52 +02:00
Conversation 7 Commits 1 Files changed 1 +61 -21
1 changed files with 61 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit d0785aaa81 - Show all commits

Readme: Better explain content types
Some checks failed
/ build (pull_request) Successful in 41s
Details
/ cleanup-staging (pull_request) Failing after 2m16s
Details

Prev Next
Stefan Bethke 2026-06-13 20:46:08 +02:00 • committed by jtbx
commit d0785aaa81

82
README.md
View file

@ -29,25 +29,59 @@ To populate the calendar data, please run `./fetch-calendar.sh` before running h
Running the hugo command without and parameters will re-generate the site in the `public` directory. Running the hugo command without and parameters will re-generate the site in the `public` directory.
To deploy the website, just copy the whole folder to a directory which is servered by the webserver of your preference. To deploy the website, just copy the whole folder to a directory which is servered by the webserver of your preference.
Please note, that the website should be re-deployed at least daily to update the "announcement" section on the front page even if there were no changed to the content. Please note that the website should be re-deployed at least daily to update the "announcement" section on the front page even if there were no changed to the content.
### Add Pages ### Previewing Changes Locally
To run a local version, just install HUGO by following the [instructions](https://gohugo.io/installation/) for your operating system. To run a local version, just install HUGO by following the [instructions](https://gohugo.io/installation/) for your operating system.
To build the website and run a development webserver, execute: To build the website and run a development webserver, execute:
```shell ```shell
hugo server hugo server --buildFuture --buildDrafts
``` ```
To also build posts in the future or in draft state, run this instead: Note: the flags `--buildFuture --buildDrafts` makes Hugo process all content, even if the `publishDate` is still in the future, or the content is marked as `draft: true` in the frontmatter.
You usually want these flags, especially if you are preparing content that should only be shown after a certain date.
Also see [Submitting Your Content](#submitting-your-content) below.
### Adding Content
There are two basic types of posts: Events and blog posts.
Hugo and the template set distinguish between these two types based on frontmatter information.
When manually creating content, you need to take extra care to use the correct frontmatter data.
See the link to the Hugo archetypes below for details.
stb marked this conversation as resolved Outdated
jtbx commented 2026-06-14 13:26:26 +02:00
Outdated
Copy link

nit-pick: I would put this line in a separate paragraph so that it stands out. And maybe even make it also bold.

Because the easiest and least error-prone way to add new content is to use the Hugo command.

nit-pick: I would put this line in a separate paragraph so that it stands out. And maybe even make it also bold. Because the easiest and least error-prone way to add new content is to use the Hugo command.
**If at all possible, use `hugo new content` with the appropriate parameters to create the new content file correctly.**
You should always set these frontmatter fields:
* `categories`: must be either `article` or `event`; see below.
* `date`: the date displayed for this content.
stb marked this conversation as resolved Outdated
jtbx commented 2026-06-13 21:20:40 +02:00
Outdated
Copy link

Not 100% correct. They will be shows for some days since we don't want to clutter the front page with "old" blog posts. If people are interested in all posts they should use an RSS reader.

Not 100% correct. They will be shows for some days since we don't want to clutter the front page with "old" blog posts. If people are interested in all posts they should use an RSS reader.
For events, that should be when the event takes place; for blog posts, it is when the post was written.
stb marked this conversation as resolved Outdated
jtbx commented 2026-06-14 13:36:25 +02:00
Outdated
Copy link

I don't understand what this sentence should tell me, especially with the explicit time of "24 hours longer".

When a publish date is set, the post will be visible on the deployed site at this date and time (or up to 20 minutes later in the worst case, because the deployment only runs every 20 minutes).
The deployed pull request however will also show posts which are in the future.

So I would rather say something like this:

- Note that the date is evaluated only during site generation, so if you pick a date in the future, it might take up to 24 hours longer before your content appears.
- Also note that if you do not specify a `publishDate`, the value of `date` will be used.
+ If a date in the future is used, the post will only appear on the web page after the specified time is due (or up to 20 minutes later since auto-deployment only runs 3 times every hour).
+ Note that the preview deployments on the staging domain will also publish posts in the future.
+ This field is only needed for events which shall be published before they actually happen (blog posts will use the `date` value as fallback for `publishDate`).
I don't understand what this sentence should tell me, especially with the explicit time of "24 hours longer". When a publish date is set, the post will be visible on the deployed site at this date and time (or up to 20 minutes later in the worst case, because the deployment only runs every 20 minutes). The deployed pull request however will also show posts which are in the future. So I would rather say something like this: ```diff - Note that the date is evaluated only during site generation, so if you pick a date in the future, it might take up to 24 hours longer before your content appears. - Also note that if you do not specify a `publishDate`, the value of `date` will be used. + If a date in the future is used, the post will only appear on the web page after the specified time is due (or up to 20 minutes later since auto-deployment only runs 3 times every hour). + Note that the preview deployments on the staging domain will also publish posts in the future. + This field is only needed for events which shall be published before they actually happen (blog posts will use the `date` value as fallback for `publishDate`). ```
stb commented 2026-06-14 20:34:59 +02:00
Outdated
Copy link

I thought auto deploy only runs once a day. If it's running multiple times each hour, there is no need to explain this in more detail. I'll add more explanation to the preview section.

I thought auto deploy only runs once a day. If it's running multiple times each hour, there is no need to explain this in more detail. I'll add more explanation to the preview section.
* `publishDate`: the date and time the content should be published.
Note that if you do not specify a `publishDate`, the value of `date` will be used.
* `title`: the headline of your content.
#### Add a Blog Entry
Blog posts (the archetype is called `article`) should be used for information that will be relevant for a longer period, for example explanations about technical, political or cultural topics.
Articles will be shown for a few days on the home page.
stb marked this conversation as resolved Outdated
jtbx commented 2026-06-13 21:21:25 +02:00
Outdated
Copy link

Wrong: date always needs to be there. publishDate can (and should) be omitted on articles.

Wrong: `date` always needs to be there. `publishDate` can (and should) be omitted on articles.
stb marked this conversation as resolved Outdated
jtbx commented 2026-06-14 13:43:03 +02:00
Outdated
Copy link

nit-pick: no comma before the "and" (because an Oxford comma is only used for lists with at least 3 items AFAIK).
And it's not really clear if the last phrase "until newer posts push them down" applies to the home page or the blog page.

nit-pick: no comma before the "and" (because an Oxford comma is only used for lists with at least 3 items AFAIK). And it's not really clear if the last phrase "until newer posts push them down" applies to the home page or the blog page.
The [blog page](https://hamburg.ccc.de/blog/) shows all posts, newest first.
stb marked this conversation as resolved Outdated
jtbx commented 2026-06-13 21:23:26 +02:00
Outdated
Copy link

I don't see a use case for a separate publish date on blog posts. We can still schedule them by using the date field, but why should there be a different publication date from the date that's shown in the post?

I don't see a use case for a separate publish date on blog posts. We can still schedule them by using the `date` field, but why should there be a different publication date from the date that's shown in the post?
In addition, the `tags:` can be used to find blog posts about certain topics.
To create a new general blog post, run a command like this:
```shell ```shell
stb marked this conversation as resolved Outdated
jtbx commented 2026-06-13 21:24:58 +02:00
Outdated
Copy link

Not 100% correct, they will also be shown up to 6 hours after the date so that events that are currently running are still present on the home page.
This time frame was enough for the usual event we host which last an evening.

Not 100% correct, they will also be shown up to 6 hours after the `date` so that events that are currently running are still present on the home page. This time frame was enough for the usual event we host which last an evening.
hugo server -D hugo new content --kind article blog/yyyy/yyyy-mm-dd-your-article-title/index.md
``` ```
If you want to create a blog post from scratch, or convert an event into a blog post, see the frontmatter data in [themes/ccchh/archetypes/article.md](themes/ccchh/archetypes/article.md).
In particular, you need to set `categories: article`.
You do not need to specify an explicit `publishDate`, as the value of `date` will be used as a fallback.
#### Add an Event Announcement #### Add an Event Announcement
There are two basic types of posts: Events and articles. Events will be shown on the home page from the frontmatter `publishDate:` until the `date:` (plus a few hours grace period).
Events will be shown on the home page from their publishing date until they have happened and shall be used for things which happen at a certain date. Use them for information that is relevant for a specific event, like a talk or a meeting.
stb marked this conversation as resolved Outdated
jtbx commented 2026-06-13 21:25:39 +02:00
Outdated
Copy link

Events should also have a publishDate since the post should usually be published before the event is happening.

Events should also have a `publishDate` since the post should usually be published before the event is happening.
This is not limited to events organized by the CCCHH, but can also be a hint to other events which we think are related to our activities. This is not limited to events organized by the CCCHH, but can also be a hint to other events which we think are related to our activities.
To create a new event blog post, run a command like this: To create a new event blog post, run a command like this:
@ -55,29 +89,35 @@ To create a new event blog post, run a command like this:
hugo new content --kind event blog/yyyy/yyyy-mm-dd-your-event-title/index.md hugo new content --kind event blog/yyyy/yyyy-mm-dd-your-event-title/index.md
``` ```
#### Add a Blog Entry If you want to create an event from scratch, or convert a blog post into an event, see the frontmatter data in [themes/ccchh/archetypes/event.md](themes/ccchh/archetypes/event.md).
In particular, you need to set `categories: event`, `date:` for the date of the event, `publishDate:` for the date the content should be published, and `location:` to whereever your event takes place.
As mentioned before, you can also create blog posts for things which aren't events.
They will only be shown in the "blog" section and posted to the RSS feeds and shall be used for things which are relevant for a longer time.
As we have much more event announcements than articles, finding articles in all blog posts can be quite a challenge.
But using these two categories enables filtering, so that the history of articles is in one list.
To create a new general blog post, run a command like this:
```shell
hugo new content --kind article blog/yyyy/yyyy-mm-dd-your-article-title/index.md
```
#### Additional Notes on Events and Articles #### Additional Notes on Events and Articles
By default the first 70 words are shown as a summary on list pages. By default the first 70 words are shown as a summary on list pages.
Please use `<!--more-->` to manually separate the summary from other post content. Please use `<!--more-->` (white space matters) to manually separate the summary from other post content.
Please prefix your folder name with a date to make browsing the content in the source code easier. Please prefix your folder name with a date to make browsing the content in the source code easier.
The date in the URL will be taken from the `date` field in the front matter. The date in the URL will be taken from the `date` field in the front matter.
Blog posts from before 2024-01-22 were imported from the previous website and have additional front matter data which is not usually needed (e.g. the lastmod value). Blog posts from before 2024-01-22 were imported from the previous website and have additional front matter data which is not usually needed (e.g. the lastmod value).
When using the commands above, the template shall have evenything you need.
#### Submitting Your Content
After creating the new content, or making changes to existing content please commit your changes with a meaningful commit message to a fresh branch.
Name the branch in a way that makes it easy to understand what the changes are, for example, the title of your new blog post.
Push the branch to git.hamburg.ccc.de, and create a new pull request.
Invite reviewers, or post the link to the PR to the [#infrastruktur:hamburg.ccc.de](https://matrix.to/#/#infrastruktur:hamburg.ccc.de) Matrix channel.
The changes you have made will be deployed to the staging website automatically (this might take a minute or two).
See the comments in the PR for the link to your preview.
You and the reviewers can use the link to preview the changes.
If you have set a `publishDate` to a date and time in the future, the preview will show the content as it would appear then.
Once at least one reviewer approves the PR, it will be merged and pushed to production.
This usually takes less than five minutes.
#### Populate the Event Calendar #### Populate the Event Calendar