Deployment

hugo-styles-template is set up for GitHub Pages via GitHub Actions rather than a committed gh-pages branch. For hosting patterns beyond this shared setup, see Hextra Deploy Site.

Recommended deployment flow

create the lesson repository from hugo-styles-template
set baseURL in hugo.toml to https://<account>.github.io/<repo>/
in GitHub, enable Pages and choose GitHub Actions as the source
push main
let the included workflow build and publish the site

The included workflow deploys on pushes to main. Enable Pages before the first push so that initial deploy run already has a configured publishing target. By default it publishes the default branch as Latest. Extra branch or tag builds come from the params.versioning block in hugo.toml. Before the deploy artifact is built, the workflow also builds a local-root version of the site and runs lychee against the rendered HTML on both pull requests and pushes. In template-based lesson repositories, the top-level workflow files are thin managed wrappers that call synced reusable workflow files maintained in hugo-styles.

Local production build

python3 scripts/build-versioned-site.py

Typical checks before publishing

go run github.com/oer-particle-physics/hugo-styles/cmd/hugo-styles-migrate@latest check .
python3 scripts/build-versioned-site.py --base-url / --destination .cache/linkcheck-site --no-minify
lychee --cache --config lychee.toml --no-progress --root-dir .cache/linkcheck-site '.cache/linkcheck-site/**/*.html'
python3 scripts/build-versioned-site.py

The first build is a link-check-only artifact. It forces baseURL to / so lychee can validate internal links against local files while still checking external links over the network. The second build remains the real deploy artifact with the production Pages URL. If a link fails because the target has really moved or disappeared, fix the content. If a trusted upstream URL is known to fail automated checks for reasons outside your control, such as an invalid TLS chain, add a narrow entry to that lesson repository’s .lycheeignore instead of enabling global insecure mode. Keep those exceptions exact and documented.

Why this uses Actions

it works for any static site generator Hugo can produce
it avoids the old branch-publishing coupling
it matches the shared-module update model more naturally

The template repo already includes the workflow and Dependabot setup required for a typical lesson repository. When you update hugo-styles, run ./scripts/sync-template-files.sh so those managed workflow files stay aligned with the pinned module version.

Versioned lesson archives

The shared workflow already knows how to build archived versions. The only thing you need to change is params.versioning in hugo.toml.

See Versioned Sites for branch/tag examples, wildcard matching, and the exact build helper behavior.

Hextra Features for Physics Lessons Troubleshooting