Hugo on Backend Engineering Strategy Tools

This Site

Thu, 18 Jun 2026 00:00:00 +0000

This started as an effort to clean up and publish existing notes — things accumulated over years of work that were sitting in various raw forms and never properly written up. The act of publishing forces a level of clarity that private notes rarely get: you have to explain the context, fill the gaps, and decide what actually matters.

It doubles as deliberate practice in documentation. Getting into the habit of writing things up properly — not just as a record of what was done, but as something useful to come back to — is a skill that compounds. The site is both the output and the exercise.

Practically it also serves as a personal reference: a place to look things up that I have actually done and know the details of, rather than re-deriving them from scratch.

Stack: Hugo static site using the Stack theme v4 via Go modules. Deployed to GitHub Pages via GitHub Actions.

Repo: Backend-Engineering-Strategy-Tools/site

Why Hugo

Static is the right default for content that does not need dynamic rendering. Hugo is fast — full site builds in milliseconds — and its template model maps well to a Go-centric mindset. The theme ecosystem is good and the Stack theme in particular supports the layout and content model needed here without significant customisation.

Build Pipeline

The GHA workflow runs on push to main:

Fetch private assets — CV and cover letter PDFs are stored in a private release on a separate repo. The workflow fetches them via GitHub API using a scoped BEST_SITE_PAT secret and writes them into static/cv/ before the build.
Hugo build — hugo --minify via the official ghcr.io/gohugoio/hugo Docker image, producing public/.
Deploy — actions/deploy-pages pushes public/ to GitHub Pages.

This keeps CV content separate from site code — the PDF repo can be updated independently without touching the site repo, and a site redeploy picks up the latest version.

Theme Customisation

Stack theme v4 is imported via go.mod. Hugo’s lookup order means local files in layouts/ or assets/ override the theme without forking it.

The main override is layouts/_default/single.html — the site uses layout: single on all content pages to get full-width rendering (no sidebar). All pages also set showReadingTime: false in front matter.

Domain

Currently served at backend-engineering-strategy-tools.github.io/site/. A redirect from best.mjnet.info is set up via an S3 static website bucket — no files in the bucket, just a redirect rule. DNS managed in Route53.

S3 bucket setup (bucket name must match domain):

aws s3api create-bucket \
 --bucket best.mjnet.info \
 --region eu-central-1 \
 --create-bucket-configuration LocationConstraint=eu-central-1

aws s3api put-public-access-block \
 --bucket best.mjnet.info \
 --public-access-block-configuration BlockPublicAcls=false,IgnorePublicAcls=false,BlockPublicPolicy=false,RestrictPublicBuckets=false

aws s3api put-bucket-website \
 --bucket best.mjnet.info \
 --website-configuration '{"IndexDocument":{"Suffix":"index.html"},"RoutingRules":[{"Redirect":{"Protocol":"https","HostName":"backend-engineering-strategy-tools.github.io","ReplaceKeyPrefixWith":"site/"}}]}'

Route53 ALIAS record pointing best.mjnet.info at the S3 website endpoint:

aws route53 change-resource-record-sets \
 --hosted-zone-id <ZONE_ID> \
 --change-batch '{
 "Changes": [{
 "Action": "CREATE",
 "ResourceRecordSet": {
 "Name": "best.mjnet.info",
 "Type": "A",
 "AliasTarget": {
 "HostedZoneId": "Z21DNDUVLTQW6Q",
 "DNSName": "s3-website.eu-central-1.amazonaws.com",
 "EvaluateTargetHealth": false
 }
 }
 }]
 }'

Z21DNDUVLTQW6Q is the fixed AWS hosted zone ID for S3 website endpoints in eu-central-1.

Content Model

Two sections with distinct purposes:

Section	Tone	What goes here
`homelab/`	Narrative, first-person	What actually happened — the sequence, dead ends, workarounds
`public-notes/`	Reference, factual	How things work — distilled, structured, without the personal journey

The separation keeps the narrative and reference writing from muddying each other. A reader looking for a quick reference does not want to read about what went wrong first; a reader following the homelab story wants the context.

projects/ and thinking/ round out the structure — projects are documented outcomes, thinking is longer-form analysis.

What’s Next

The current setup — Hugo on GitHub Pages — is the right foundation for a content-heavy site. A few things are planned or in progress:

Custom domain — best.mjnet.info redirect via S3 + Route53 (see Domain section above). Proper custom domain with HTTPS as a follow-up.
Better build pipeline — replacing the Makefile with a Dagger Go module for local/CI parity and pinned Hugo versions.
More content — the backlog of notes and projects is long. The site grows as things get cleaned up and published.

Longer term, the intent is to grow this into a more multi-faceted site — login-protected sections, dynamic content, interactive tooling. Hugo handles the static part well; the approach is to add separate paths alongside it for authentication and dynamic content rather than replacing the static foundation. The static site stays fast and low-cost, dynamic parts layer in where they are actually needed.

Hugo

Mon, 01 Jan 2024 00:00:00 +0000

Hugo is a static site generator written in Go. Content is Markdown, templates are Go HTML templates, and the output is plain HTML/CSS/JS — no server-side runtime, no database. Build times are fast even for large sites; most builds complete in under a second. This site is built with Hugo.

Structure

content/ # Markdown pages — mirrors the URL structure
layouts/ # Template overrides (Hugo prefers local files over theme files)
assets/ # CSS, JS, images processed by Hugo Pipes
static/ # Files copied as-is into the output
themes/ # Theme(s), typically pulled via Go modules
config.yaml # Site configuration

Content files use YAML front matter to set metadata:

---
title: "My Page"
date: 2026-06-04
draft: false
tags: ["example"]
---

Page content here.

Themes via Go modules

Themes are imported as Go modules in go.mod. To override a theme template or style, mirror the file path under layouts/ or assets/ — Hugo’s lookup order prefers local files over theme files, so the override takes effect without touching the theme itself.

Build and serve

# Serve locally with draft and future content enabled
hugo server -D --buildFuture

# Build to public/
hugo --minify

Sections and taxonomies

Hugo’s content model is built around sections (top-level directories in content/) and taxonomies (tags, categories). Each section and taxonomy gets its own listing page automatically. _index.md in a section directory controls the listing page’s content and front matter.

Resources

Reveal.js

Mon, 01 Jan 2024 00:00:00 +0000

Reveal.js is a browser-based presentation framework. Slides are HTML rendered in a browser — transitions, speaker notes, code highlighting, nested slides, and a presenter view all included. The source can be plain HTML or Markdown. Stored in Git, versioned, diffable, buildable in CI. No PowerPoint, no Keynote, no binary blobs.

The practical workflow for a docs-as-code setup: write slides in Markdown, serve with Hugo using the Reveal Hugo theme, export to PDF with DeckTape for distribution.

Hugo integration — Reveal Hugo

Reveal Hugo is a Hugo theme that turns a Hugo site into a Reveal.js presentation builder. Add the theme, create a content directory, and Hugo renders each section as a Reveal.js presentation.

Slides live in a Hugo content directory. Horizontal slides are separated by ---, vertical slides (a column within a section) by ___:

+++
title = "My Talk"
outputs = ["Reveal"]
+++

# First slide

---

# Second slide

Horizontal neighbour of the first.

___

## Second slide, vertical child

Press down to reach this one.

---

# Third slide

outputs = ["Reveal"] in the front matter tells Hugo to use the Reveal layout instead of the standard page layout.

Configuration

Reveal.js options set in config.yaml under [params.reveal_hugo]:

params:
 reveal_hugo:
 theme: "black"
 highlight_theme: "monokai"
 slide_number: true
 transition: "slide"

Per-slide overrides go in a front matter block on that slide.

Shortcodes

Reveal Hugo provides shortcodes for Reveal.js features:

{{< slide background-image="bg.jpg" >}}

# Slide with background image

{{< /slide >}}

{{% note %}}
Speaker notes — visible in presenter mode, not on screen.
{{% /note %}}

Exporting to PDF with DeckTape

DeckTape drives a headless browser through each slide and captures a PDF that preserves the rendered layout — fonts, colours, syntax highlighting. The simplest path is Docker:

# Export from a live URL
docker run --rm -t -v $(pwd):/slides \
 astefanutti/decktape \
 https://example.com/my-presentation slides.pdf

# Export from a local Hugo server (hugo server running on 1313)
docker run --rm -t --net=host -v $(pwd):/slides \
 astefanutti/decktape \
 http://localhost:1313/presentations/my-talk/ slides.pdf

DeckTape auto-detects the presentation framework. Override the output size with --size 1920x1080 if needed.