Deploy docs site with Hugo via GitHub Actions#628
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 migrates the project's documentation system to Hugo, replacing the manual generation logic in the release script. It introduces a new Hugo configuration that mounts the project README as the main content, along with custom layouts and CSS. Additionally, mise configuration is updated to include Hugo and new tasks for building and serving the documentation site. The review feedback suggests enhancing the HTML template by dynamically setting the language attribute and making the API documentation link configurable via the site settings.
| @@ -0,0 +1,207 @@ | |||
| <!doctype html> | |||
| <html lang="en"> | |||
There was a problem hiding this comment.
The lang attribute is hardcoded to "en". While appropriate for the current content, it is better practice to use the site's configured language to support future internationalization.
| <html lang="en"> | |
| <html lang="{{ .Site.Language.LanguageCode | default "en" }}"> |
| <body> | ||
| <nav class="page-nav"> | ||
| <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>Overview</a> | ||
| <a href="{{ "doc/latest/" | relURL }}">API documentation</a> |
There was a problem hiding this comment.
The link to the API documentation is hardcoded to doc/latest/. If the Javadoc directory structure changes or if you want to link to a specific version, this will need manual updates. Consider if this should be a configurable parameter in hugo.toml.
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.
For STF-448.
Post-merge steps
and a sample
/doc/latest/still loads after the next workflow rungh-pages, drop the legacy Jekyll sourcefiles
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