From d0785aaa81268402eb886302b2a0c02182ec9a4c Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Sat, 13 Jun 2026 20:46:08 +0200 Subject: [PATCH] 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