Deploy docs site with Hugo via GitHub Actions#399
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/` Doxygen subtree exactly as it lives on gh-pages today. 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>
![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 introduces a Hugo-based documentation system for the minFraud .NET API, including configuration, layout templates, and automated build/serve tasks via mise. Feedback identifies critical issues with hallucinated tool versions in the mise.lock file for Hugo, Node.js, and Prettier, which will cause environment setup to fail. Additionally, improvements are suggested for the documentation templates to better support internationalization by replacing hardcoded language attributes and UI strings with Hugo's built-in configuration and i18n features.
| url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345520544" | ||
|
|
||
| [[tools.hugo]] | ||
| version = "0.161.1" |
There was a problem hiding this comment.
The version 0.161.1 for Hugo appears to be hallucinated. The current latest stable version of Hugo is significantly lower (around 0.143.x). This will cause tool installation to fail in CI and local environments. Please regenerate the lockfile by running mise lock to capture valid versions.
| url = "https://nodejs.org/dist/v25.8.1/node-v25.8.1-win-x64.zip" | ||
|
|
||
| [[tools.node]] | ||
| version = "26.1.0" |
There was a problem hiding this comment.
The version 26.1.0 for Node.js does not exist (Node.js major versions are currently at 23). This hallucinated version will break the environment setup. Please regenerate the lockfile using mise lock.
| backend = "npm:prettier" | ||
|
|
||
| [[tools."npm:prettier"]] | ||
| version = "3.8.3" |
There was a problem hiding this comment.
The version 3.8.3 for Prettier is non-existent (the current latest is 3.5.x). This will cause installation failures. Please regenerate the lockfile.
| @@ -0,0 +1,207 @@ | |||
| <!doctype html> | |||
| <html lang="en"> | |||
There was a problem hiding this comment.
The lang attribute is hardcoded to "en". It is better practice to use the site's configured language to support future internationalization and ensure consistency with Hugo's configuration.
| <html lang="en"> | |
| <html lang="{{ .Site.LanguageCode | default 'en' }}"> |
| <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 navigation labels "Overview" and "API documentation" are hardcoded. Consider using Hugo's i18n features (e.g., {{ i18n "overview" }}) to manage these strings. This facilitates future localization and maintains a cleaner separation between content and presentation.
| @@ -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 string "Link to". This should be externalized to a translation file using Hugo's i18n system for better maintainability and accessibility support across different locales.
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.
The historical Doxygen output under
/doc/vX.Y.Z/(frozen since 2022)is preserved untouched by the workflow's
keep_files: true, matchingthe Terraform comment that calls out the intent of keeping old API doc
links alive.
docs/onmainand mountsREADME.mdasthe home page
/doc/latest/.github/workflows/pages.ymlbuilds withmise run build-docsandpushes to
gh-pagesviapeaceiris/actions-gh-pageswithkeep_files: truerelease.shchange needed — this repo's release script doesn'tpublish to gh-pages
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