Skip to content
maxime.bertrand homelab

Decisions

ADR 0013: A custom public site, generated by Hugo and served by the homelab

The portfolio is a static site with its own design, built from docs/ and published through a Cloudflare tunnel.

accepted #site#cloudflare#documentation 2 min read

Context

The repository’s public documentation also serves as a portfolio. A standard documentation theme is readable, but looks like every other documentation site: the site needed an identity of its own, presenting the project (principles, architecture, decisions, journal) without duplicating the content.

Options considered

  1. MkDocs Material: excellent for technical documentation, but a generic look.
  2. A JavaScript framework (Astro, Next.js…): very flexible, but a Node.js toolchain to maintain for a static site.
  3. Hugo with a custom-written theme: a single binary, a build in a few tens of milliseconds, and full control over the HTML and CSS.

Decision

Hugo, with a theme written for this site (templates, CSS and dependency-free JavaScript). The content remains the single source docs/: Hugo mounts it directly, and links between Markdown files become links between pages. The site is served by nginx on a dedicated VM and published through Cloudflare Tunnel (ADR 0002).

Consequences

  • Writing a documentation page is enough to publish it; the build is strict (the slightest warning stops it), and checked by CI.
  • No cookies or trackers; a content security policy (CSP) allows only the site itself and the diagram library, loaded only on pages that contain diagrams and verified by hash (SRI).
  • The theme has to be maintained by hand: no free updates from a community theme.
  • Added on 02/10/2026: the site is bilingual. English pages live in docs/en/, with the same file names as their French originals, so that each page links to its translation.