Deploy docs site with Hugo via GitHub Actions#374
Conversation
![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" |
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request transitions the project's documentation from a manually generated Markdown file to a Hugo-based site. It introduces a new Hugo configuration, layouts, and CSS, while updating the release script to remove the old documentation generation logic. Hugo has also been added to the mise configuration for local development and building. Feedback focuses on improving internationalization and accessibility by replacing hardcoded English strings and language attributes with Hugo's built-in functions and site parameters.
| @@ -0,0 +1,207 @@ | |||
| <!doctype html> | |||
| <html lang="en"> | |||
There was a problem hiding this comment.
The lang attribute is hardcoded to "en". For better accessibility and to follow Hugo best practices, it is recommended to use the site's configured language code with a fallback.
| <html lang="en"> | |
| <html lang="{{ .Site.LanguageCode | default 'en' }}"> |
| <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active" aria-current="page"{{ end }}>Overview</a> | ||
| <a href="{{ "/doc/latest/" | relURL }}">API documentation</a> |
There was a problem hiding this comment.
The navigation labels "Overview" and "API documentation" are hardcoded in English. For better maintainability and future internationalization support, consider using Hugo's i18n function.
| @@ -0,0 +1,4 @@ | |||
| <h{{ .Level }} id="{{ .Anchor }}"> | |||
| {{- .Text | safeHTML -}} | |||
| <a class="heading-anchor" href="#{{ .Anchor }}" aria-label="Link to {{ .PlainText }}">#</a> | |||
There was a problem hiding this comment.
The aria-label contains a hardcoded English string ("Link to"). To support internationalization, consider using Hugo's i18n function or a site parameter for this label.
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>
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