From 717ef682218e59de6b4d09d767ae225422fb5ee9 Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Sat, 13 Jun 2026 20:46:08 +0200 Subject: [PATCH 1/7] Better explain content types --- README.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 8bf8426..a3e7cd5 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,9 @@ 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. 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 build the website and run a development webserver, execute: @@ -44,16 +44,9 @@ To also build posts in the future or in draft state, run this instead: hugo server -D ``` -#### Add an Event Announcement +### Adding Content -There are two basic types of posts: Events and articles. -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. -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: -```shell -hugo new content --kind event blog/yyyy/yyyy-mm-dd-your-event-title/index.md -``` +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. If at all possible, use `hugo new content` with the appropriate parameters to create the new content file correctly. #### Add a Blog Entry @@ -68,16 +61,30 @@ To create a new general blog post, run a command like this: 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 an 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` and remove any `location:`. + +#### Add an Event Announcement + +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. + +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: +```shell +hugo new content --kind event blog/yyyy/yyyy-mm-dd-your-event-title/index.md +``` + +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` and `location: Z9` (or whereever your event takes place). + #### Additional Notes on Events and Articles By default the first 70 words are shown as a summary on list pages. -Please use `` to manually separate the summary from other post content. +Please use `` (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. 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). -When using the commands above, the template shall have evenything you need. #### Populate the Event Calendar From 242ef58bc2a6f123cbc713607aeb143964f00871 Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Sat, 13 Jun 2026 20:50:55 +0200 Subject: [PATCH 2/7] Clarify date / publishDate --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a3e7cd5..07c8c77 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ To create a new general blog post, run a command like this: 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 an 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` and remove any `location:`. +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` and remove any `date:` or `location:`. Note that `publishDate:` is fine, as it determines when the content will start appearing on the the site. #### Add an Event Announcement @@ -74,7 +74,7 @@ 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 ``` -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` and `location: Z9` (or whereever your event takes place). +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, and `location: Z9` (or whereever your event takes place). #### Additional Notes on Events and Articles From 640658f8c3116cadfbfea93e38800d17e21372ca Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Sat, 13 Jun 2026 21:01:14 +0200 Subject: [PATCH 3/7] clarify and correct language --- README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 07c8c77..3f5e69b 100644 --- a/README.md +++ b/README.md @@ -50,11 +50,7 @@ There are two basic types of posts: Events and blog posts. Hugo and the template #### Add a Blog Entry -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. +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 in chronological order on the [blog main page](https://hamburg.ccc.de/blog/), until newer posts push them down. 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 @@ -65,7 +61,7 @@ If you want to create a blog post from scratch, or convert an event into a blog #### Add an Event Announcement -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. +Events will be shown on the home page from the frontmatter `publishDate` until the `date:`. Use them for information that is relevant for a specific event, like a talk or a meeting. 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. From bfde817bc64f56abbf82c4cdd93407303189dedd Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Sat, 13 Jun 2026 21:17:03 +0200 Subject: [PATCH 4/7] Improve source formatting A single sentence per line --- README.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3f5e69b..0afd0fe 100644 --- a/README.md +++ b/README.md @@ -46,22 +46,31 @@ hugo server -D ### 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. If at all possible, use `hugo new content` with the appropriate parameters to create the new content file correctly. +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. +If at all possible, use `hugo new content` with the appropriate parameters to create the new content file correctly. #### 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 in chronological order on the [blog main page](https://hamburg.ccc.de/blog/), until newer posts push them down. In addition, the `tags:` can be used to find blog posts about certain topics. +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 in chronological order on the [blog main page](https://hamburg.ccc.de/blog/), until newer posts push them down. +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 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` and remove any `date:` or `location:`. Note that `publishDate:` is fine, as it determines when the content will start appearing on the the site. +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` and remove any `date:` or `location:`. +Note that `publishDate:` is fine, as it determines when the content will start appearing on the the site. #### Add an Event Announcement -Events will be shown on the home page from the frontmatter `publishDate` until the `date:`. Use them for information that is relevant for a specific event, like a talk or a meeting. +Events will be shown on the home page from the frontmatter `publishDate` until the `date:`. +Use them for information that is relevant for a specific event, like a talk or a meeting. 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. @@ -70,7 +79,8 @@ 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 ``` -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, and `location: Z9` (or whereever your event takes place). +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, and `location: Z9` (or whereever your event takes place). #### Additional Notes on Events and Articles From 6c73476ca68052a19e000ce4405db519bd8a98df Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Sat, 13 Jun 2026 21:49:51 +0200 Subject: [PATCH 5/7] Improve explanations further --- README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0afd0fe..ca087b4 100644 --- a/README.md +++ b/README.md @@ -51,11 +51,20 @@ Hugo and the template set distinguish between these two types based on frontmatt 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. 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. + For events, that should be when the event takes place; for blog posts, it is when the post was written. +* `publishDate`: the date and time the content should be published. + 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. +* `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 in chronological order on the [blog main page](https://hamburg.ccc.de/blog/), until newer posts push them down. +Articles will be shown for a few days on the home page, and in chronological order on the [blog main page](https://hamburg.ccc.de/blog/), until newer posts push them down. 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: @@ -64,12 +73,12 @@ 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` and remove any `date:` or `location:`. -Note that `publishDate:` is fine, as it determines when the content will start appearing on the the site. +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 -Events will be shown on the home page from the frontmatter `publishDate` until the `date:`. +Events will be shown on the home page from the frontmatter `publishDate:` until the `date:` (plus a few hours grace period). Use them for information that is relevant for a specific event, like a talk or a meeting. 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. @@ -80,7 +89,7 @@ hugo new content --kind event blog/yyyy/yyyy-mm-dd-your-event-title/index.md ``` 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, and `location: Z9` (or whereever your event takes place). +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. #### Additional Notes on Events and Articles From dca8a2afb4382fca2fec8ccd3b1c087a86c69f32 Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Sun, 14 Jun 2026 20:35:22 +0200 Subject: [PATCH 6/7] changes based on jtbx's review --- README.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ca087b4..6a0fe10 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,12 @@ Please note that the website should be re-deployed at least daily to update the 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: ```shell -hugo server +hugo server --buildFuture --buildDrafts ``` -To also build posts in the future or in draft state, run this instead: -```shell -hugo server -D -``` +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 @@ -50,21 +49,21 @@ 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. -If at all possible, use `hugo new content` with the appropriate parameters to create the new content file correctly. + +**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. For events, that should be when the event takes place; for blog posts, it is when the post was written. * `publishDate`: the date and time the content should be published. - 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. + 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, and in chronological order on the [blog main page](https://hamburg.ccc.de/blog/), until newer posts push them down. +Articles will be shown for a few days on the home page. The [blog page](https://hamburg.ccc.de/blog/) shows all posts, newest first. 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: @@ -101,6 +100,18 @@ 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). +#### 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 The event calendar table is filled from the Nextcloud iCal feed. From d0785aaa81268402eb886302b2a0c02182ec9a4c Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Sat, 13 Jun 2026 20:46:08 +0200 Subject: [PATCH 7/7] Readme: Better explain content types --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 8bf8426..666a785 100644 --- a/README.md +++ b/README.md @@ -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. 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 build the website and run a development webserver, execute: ```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. + +**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. + For events, that should be when the event takes place; for blog posts, it is when the post was written. +* `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. +The [blog page](https://hamburg.ccc.de/blog/) shows all posts, newest first. +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 -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 -There are two basic types of posts: Events and articles. -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. +Events will be shown on the home page from the frontmatter `publishDate:` until the `date:` (plus a few hours grace period). +Use them for information that is relevant for a specific event, like a talk or a meeting. + 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: @@ -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 ``` -#### Add a Blog Entry - -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 -``` +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. #### Additional Notes on Events and Articles By default the first 70 words are shown as a summary on list pages. -Please use `` to manually separate the summary from other post content. +Please use `` (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. 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). -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