Deploy docs site with Hugo via GitHub Actions#374
Conversation
Build with `mise run build-docs`, preview with `mise run serve-docs`. The site mounts the existing `README.md` as the home page so the source of truth stays in one place. A small pill nav links from Overview to the versioned API documentation that lives on the `gh-pages` branch under `doc/latest/`. CSS is inlined in the layout template — no external dependencies. Same Charter serif + forest-green design as the MaxMind-DB spec site. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploys the Hugo docs site on push to main. The workflow builds the site with `mise run build-docs` and pushes the rendered output onto the existing `gh-pages` branch with `keep_files: true` — that preserves every `/doc/vX.Y.Z/` Javadoc subtree exactly as the release script publishes them. Pages keeps deploying from `gh-pages`, so no Terraform change is needed for this repo. All actions are SHA-pinned. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hugo on `main` now owns the Pages index, so the release script no longer needs to write a Jekyll front-matter wrapper around README.md on the gh-pages branch. The Javadoc-publishing block that creates `doc/$tag/` and updates the `doc/latest` symlink is unchanged — that versioned tree continues to live on gh-pages and is preserved by the new workflow's `keep_files: true`. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request transitions the project's documentation generation from a manual shell script to a Hugo-based system. It introduces Hugo configuration, layouts, and new mise tasks for building and serving the documentation. Feedback suggests adding the --cleanDestinationDir flag to the Hugo build command in mise.toml to ensure that stale files from previous builds are removed from the output directory.
|
|
||
| [tasks.build-docs] | ||
| description = "Build the docs site with Hugo" | ||
| run = "hugo --source docs --minify" |
There was a problem hiding this comment.
It is recommended to add the --cleanDestinationDir flag to the Hugo build command. This ensures that any stale files from previous builds (e.g., if a file was deleted or renamed in the source) are removed from the output directory, preventing them from being accidentally published to the gh-pages branch.
| run = "hugo --source docs --minify" | |
| run = "hugo --source docs --minify --cleanDestinationDir" |
1 participant
Summary
Migrates the Pages index from Jekyll on
gh-pagesto a Hugo build thatpublishes back onto
gh-pagesfrom GitHub Actions. All CSS is nowinlined in the layout template — no external CDN dependencies.
docs/onmainand mountsREADME.mdas thehome page
/doc/latest/.github/workflows/pages.ymlbuilds withmise run build-docsandpushes to
gh-pagesviapeaceiris/actions-gh-pageswithkeep_files: true, so every/doc/vX.Y.Z/Javadoc subtree staysuntouched
dev-bin/release.shno longer regenerates the Jekyllindex.md;the Javadoc-publishing block is unchanged
Same design as MaxMind-DB PR #221.
Preview locally with
mise run serve-docs.For STF-448.
Post-merge steps
and a sample
/doc/latest/still loads after the next workflow rungh-pages, drop the legacy Jekyll source(
_config.yml,_layouts/, the release-generatedindex.md,stylesheets/pygments.css,Gemfile*)Pages source stays on
gh-pages— no Terraform change for this repo.Test plan
mise run build-docssucceeds with no warnings<title>,<h1>, and pill nav are correctstatic-gh.maxmind.comreferences in the new sitemain)and
/doc/vX.Y.Z/subtrees are preserved🤖 Generated with Claude Code