news.opencommit.eu

Source for the OpenCommit news site, published at https://news.opencommit.eu.

A Hugo site using the oc-hugo-theme, consumed as a Hugo module. Content is Markdown; there is no database and no build step beyond Hugo.

Requirements

• Hugo extended, 0.128.0 or newer (0.158+ recommended — the theme uses config keys and template properties that older versions do not have)
• Go, for resolving the theme module

The theme is fetched over the network on first build. It is public, so no credentials are needed.

Everyday commands

make serve    # live-reloading preview on http://localhost:1313
make build    # production build into public/
make check    # build and verify the output

make check is the one to run before opening a pull request. It fails if baseURL ever leaks a localhost URL into the output — a mistake that is easy to make and invisible until the site is live, because every canonical link, social preview and sitemap entry would point at your own machine.

Writing a post

hugo new posts/my-post/index.md

The front matter every post uses, and the two conventions that are easy to get wrong, are documented in content/posts/how-to-publish/index.md. In short:

• authors is a list. The singular author: key still renders a byline but drops the post out of /authors/, which is a quiet way to lose it.
• An author's directory must be the URL-safe form of their name: Benoit Schipper lives in content/authors/benoit-schipper/.
• featuredImage must be a raster format. An SVG cover yields a social card that Twitter, Facebook, LinkedIn and Slack all decline to render.

Layout

content/
  posts/            articles, one page bundle per post
  authors/          one directory per author, named as the URL-safe author name
  categories/       category landing page
  tags/             tag landing page
  about.md          about the foundation
  contact.md        contact details
  search.md         search page (queries the build-time JSON index)
assets/img/         avatars and cover images
hugo.toml           site configuration, menus and taxonomy definitions
go.mod, go.sum      pins the theme version
Dockerfile          builds the site and serves it with nginx
Makefile            local build, preview and verification
.forgejo/workflows/ Forgejo Actions CI and release

public/ and resources/ are build output and are not tracked.

Deployment

The site builds to static files and is served by nginx. Dockerfile produces that image: Hugo builds with HUGO_ENV=production, and the result is copied into an nginx image. Both base images are pinned by digest.

Continuous integration runs on OpenCommit's own Forgejo, in .forgejo/workflows/.

ci.yml runs on every push to main and on every pull request. It builds the image — which is also the site build, so the runner needs no Hugo or Go toolchain — and then asserts the two invariants make check enforces locally against the files the image serves: no localhost URLs, and a robots.txt. It uses no secrets, so pull requests from forks work.

release.yml runs on v* tags. It has two jobs: build does the same verified build, and publish only runs once that succeeds, so a site that does not build never reaches the registry. Publishing needs the ORG_REGISTRY_USER and ORG_REGISTRY_TOKEN repository secrets, and the package registry has to be enabled in the repository settings.

Pushing v0.1.0 publishes these tags to the container package opencommit.eu/opencommit/news.opencommit.eu:

Tag	Purpose
0.1.0	the release, for pinning
0.1	the minor series
0	the major series
latest	floating pointer at the newest release

Nothing deploys the image yet. opengit-eu/infra has no manifest for this site, and it is still a GitHub repository, so the ArgoCD hand-off the other sites use is not wired up here.

The theme

hugo.toml imports opencommit.eu/opencommit/oc-hugo-theme, pinned in go.mod. To move to a newer release:

hugo mod get opencommit.eu/opencommit/oc-hugo-theme@v0.2.0

Known upstream issues

The theme currently uses two properties that Hugo has deprecated, so every build prints two warnings:

Used	Replacement	Deprecated in
.Language.LanguageCode	.Language.Locale	0.158
.Page.IsNode	.Page.IsBranch	0.163

Neither is caused by this site, and neither breaks the build today, but both will become hard errors in a future Hugo. make check reports them rather than failing on them.