Deploy docs site with Hugo and GitHub Actions#171
Conversation
Build with `mise run build-docs`, preview with `mise run serve-docs`. The site renders the README as the home page via a module mount; CSS is inlined in the layout template with no external dependencies. Hover any heading to reveal a `#` anchor link. Charter serif body text, forest-green accent on field-name headings — 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 "Deploy from a branch" (gh-pages) to "GitHub Actions" — handled in the mm_website Terraform PR. The legacy gh-pages branch can then be deleted. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The release script no longer needs to clone the gh-pages branch and regenerate a Jekyll index page from README.md — the new Hugo workflow on main owns the docs site, and there is no versioned doc tree on gh-pages for this repo to preserve. 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 from a manual Jekyll-based process to Hugo. It removes the legacy site generation logic from the release script, updates the .gitignore, and adds Hugo configuration, templates, and a mise.toml for environment management. Feedback recommends restoring the descriptive site title for improved SEO and pinning the Hugo version to ensure deterministic builds.
| @@ -0,0 +1,14 @@ | |||
| baseURL = "https://maxmind.github.io/mod_maxminddb/" | |||
| title = "mod_maxminddb" | |||
There was a problem hiding this comment.
The site title has been significantly shortened compared to the previous Jekyll implementation. The original title (mod_maxminddb - an Apache module that allows you to query MaxMind DB files) provided much better context for search engine results and browser tabs. Consider restoring the descriptive title to maintain SEO and user experience.
| title = "mod_maxminddb" | |
| title = "mod_maxminddb - an Apache module that allows you to query MaxMind DB files" |
| ] | ||
|
|
||
| [tools] | ||
| hugo = "latest" |
There was a problem hiding this comment.
Using latest for the Hugo version can lead to non-deterministic builds if a future update introduces breaking changes or alters rendering behavior. It is recommended to pin a specific version to ensure consistency across different development environments and CI/CD pipelines.
| hugo = "latest" | |
| hugo = "0.143.1" |
1 participant
Summary
Migrates the docs site from Jekyll on
gh-pagesto a Hugo build deployedvia GitHub Actions. All CSS is now inlined in the layout template — no
external CDN dependencies.
docs/onmain; the home page mountsREADME.mdso the source of truth stays in one place.github/workflows/pages.ymlbuilds withmise run build-docsanddeploys via the GitHub Actions Pages environment
dev-bin/make-release.shno longer clones thegh-pagesbranch orregenerates
index.mdSame 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 fromgh-pagesto GitHub Actionsgh-pagesbranchTest plan
mise run build-docssucceeds with no warningsgrep -r static-gh docs/returns nothing<title>and<h1>are correct; CSS is inlinedmain)🤖 Generated with Claude Code