Deploy docs site with Hugo and GitHub Actions#486
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. CSS is inlined in the layout template with no external dependencies. Hover any heading to reveal a `#` anchor link. Same 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. Uses the same mise-action pattern as PR #221. All actions are SHA-pinned. After merge, the Pages source needs to flip from the main branch to GitHub Actions — handled in the mm_website Terraform PR. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
With Pages moving to the GitHub Actions workflow that builds the Hugo docs site, the bare `_config.yml` that previously engaged the default Jekyll theme is no longer needed. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Modver resultThis report was generated by Modver, This PR does not require a change in your module’s version number. |
There was a problem hiding this comment.
Code Review
This pull request introduces a Hugo-based documentation site, including configuration files, layouts, and integration with the mise tool for building and serving the site. Feedback highlights critical issues with the mise.lock file, which contains non-existent tool versions that will cause installation failures. Additionally, the Hugo configuration needs to mount the doc/ directory to ensure that links within the README to external documentation files are not broken.
| [[tools.hugo]] | ||
| version = "0.161.1" | ||
| backend = "aqua:gohugoio/hugo" |
There was a problem hiding this comment.
The versions specified in this lock file (e.g., Hugo 0.161.1, and elsewhere in the file Go 1.26.1 and Node 25.8.0) do not exist in the current ecosystem. It appears these versions were hallucinated by the AI tool used to generate this pull request. This will cause mise install to fail as it won't be able to find these releases. Please regenerate the lock file using the mise lock command in your local environment to capture valid tool versions.
| [[module.mounts]] | ||
| source = "../README.md" | ||
| target = "content/_index.md" |
There was a problem hiding this comment.
The current configuration only mounts the root README.md. However, the README.md contains links to other documentation files located in the doc/ directory (e.g., doc/docker.md, doc/geoipupdate.md). These files will not be included in the Hugo build, resulting in broken links on the deployed documentation site. You should mount the doc/ directory as well to ensure all referenced documentation is available.
| [[module.mounts]] | |
| source = "../README.md" | |
| target = "content/_index.md" | |
| [[module.mounts]] | |
| source = "../README.md" | |
| target = "content/_index.md" | |
| [[module.mounts]] | |
| source = "../doc" | |
| target = "content/doc" |
Summary
Migrates the docs site at https://maxmind.github.io/geoipupdate/ from
the default Jekyll theme (rendered from
mainwith a bare_config.yml)to a Hugo build deployed via GitHub Actions. All CSS is inlined in the
layout template — no external CDN dependencies.
docs/and mountsREADME.mdas the home page.github/workflows/pages.ymlbuilds withmise run build-docsanddeploys via the GitHub Actions Pages environment
_config.ymlis removedSame design as MaxMind-DB PR #221: Charter serif body text, forest-green
accent on field-name headings, hover
#anchor links.Preview locally with
mise run serve-docs.For STF-448.
Post-merge steps
mm_websiteto switch Pages source fromthe
mainbranch to GitHub ActionsTest plan
mise run build-docssucceeds with no warnings<title>and<h1>are correct; CSS is inlined; noexternal CDN references in the output
main)🤖 Generated with Claude Code