Skip to content

8. Use Hugo for Static Site

Status

Superseded by ADR-0017

Context

We needed a way to publish a public-facing website for StartMeUp.nz that was:

  • Easy to edit using Markdown
  • Compatible with Git and CI/CD workflows
  • Lightweight and fast to deploy
  • Customizable, but with good defaults out of the box
  • Open Source and widely supported

This is really just an evaluation, the only other static site generator I peronally have experience w/ is Sphinx, and I didn't really feel like it was the right fit for this kind of site. A few real humans recommended Hugo to me as a good fast static site generator, and ChatGPT recommended the "Ananke" theme.

Decision

We chose to use Hugo with the Ananke theme for our static site.

Hugo gives us:

  • Speed — rebuilds are instant
  • Easy way to test locally w/ "hugo server"
  • Simple Markdown-based content structure
  • Easy theming and layout overrides
  • Strong community and documentation
  • Clean integration with GitLab Pages and CI

Consequences

  • The website will live under website/
  • Future contributors can add/edit content using Markdown
  • Theme customization can be done via layouts/ overrides
  • When cloning the repo, contributors must include the theme submodule:
git clone --recurse-submodules git@gitlab.com:smunz/startmeup.nz.git

Mentioned on the README ^ since no one really comes here to read docs.