Deploy docs site with Hugo and GitHub Actions by oschwald · Pull Request #171 · maxmind/mod_maxminddb

oschwald · 2026-05-15T22:25:48Z

Summary

Migrates the docs site from Jekyll on gh-pages to a Hugo build deployed
via GitHub Actions. All CSS is now inlined in the layout template — no
external CDN dependencies.

Hugo site lives under docs/ on main; the home page mounts
README.md so the source of truth stays in one place
.github/workflows/pages.yml builds with mise run build-docs and
deploys via the GitHub Actions Pages environment
dev-bin/make-release.sh no longer clones the gh-pages branch or
regenerates index.md

Same 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

Apply Terraform in mm_website to switch Pages source from
gh-pages to GitHub Actions
Verify the site at https://maxmind.github.io/mod_maxminddb/
Delete the legacy gh-pages branch

Test plan

mise run build-docs succeeds with no warnings
grep -r static-gh docs/ returns nothing
Rendered <title> and <h1> are correct; CSS is inlined
Build job passes in CI (deploy only runs on main)
After merge + Terraform apply, verify the live site renders correctly

🤖 Generated with Claude Code

gemini-code-assist

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.

gemini-code-assist · 2026-05-15T22:27:19Z

@@ -0,0 +1,14 @@
+baseURL = "https://maxmind.github.io/mod_maxminddb/"
+title = "mod_maxminddb"


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.

Suggested change

title = "mod_maxminddb"

title = "mod_maxminddb - an Apache module that allows you to query MaxMind DB files"

gemini-code-assist · 2026-05-15T22:27:19Z

+]
+
+[tools]
+hugo = "latest"


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.

Suggested change

hugo = "latest"

hugo = "0.143.1"

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>

horgh · 2026-05-20T02:44:00Z

+]
+
+[tools]
+hugo = "latest"


Should this be in mise.lock?

Addressed in 94fd59c — mise.lock is now tracked with Hugo's seven platform entries (linux-x64/arm64 +musl, macos-x64/arm64, windows-x64). The lockfile was missing entirely because I created mise.toml from scratch in this PR and never committed the generated lock.

(Claude, responding on behalf of @oschwald.)

horgh · 2026-05-20T02:44:15Z

@@ -0,0 +1,13 @@
+title = "mod_maxminddb"
+disableKinds = ["taxonomy"]


Same feedback as on geoipupdate PR.

Addressed in f1024eb — disableKinds = ["taxonomy", "term", "RSS"]. Same fix shipped on all 11 docs PRs.

(Claude, responding on behalf of @oschwald.)

`disableKinds = ["taxonomy"]` only disables the taxonomy list page; post-Hugo-0.73 individual term pages are a separate kind. The site declares no taxonomies, so neither list nor term pages have content, but the config now matches its stated intent. Disabling RSS also suppresses an empty `index.xml` that nothing subscribes to. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Hugo's built-in fallback renders an empty `<main></main>` for the 404 page. Provide a minimal "Page not found" body with a link back to the site home, reusing the Charter/forest-green design tokens from the main layout. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The lockfile was never committed alongside the new mise.toml, so CI resolved `hugo = "latest"` afresh on every run. Track the lock now with all platform entries so builds are reproducible. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

oschwald · 2026-05-20T15:16:00Z

/gemini review

gemini-code-assist

Code Review

This pull request transitions the project's documentation from a manual script-based process to a Hugo-based static site generator. It removes the legacy gh-pages update logic from the release script and introduces a new docs/ directory containing Hugo configurations, layouts, and templates. Additionally, mise is integrated for tool management and task automation. Feedback was provided regarding significant CSS duplication between the 404 and default layouts, with a recommendation to move shared styles into a Hugo partial to improve maintainability.

oschwald · 2026-05-20T16:54:31Z

/gemini review

gemini-code-assist

Code Review

This pull request migrates the documentation system from a manual Jekyll process to a Hugo-based setup managed by mise, removing legacy deployment logic from the release script. Feedback identifies a missing GitHub Actions workflow file and the loss of version-specific metadata on the documentation site. Reviewers also suggest restoring the full descriptive site title for SEO and inlining CSS within the templates to align with the stated goal of minimizing external dependencies.

I am having trouble creating individual review comments. Click here to see my feedback.

mise.toml (18-24)

The PR description mentions a new GitHub Actions workflow .github/workflows/pages.yml that uses the build-docs task, but this file is missing from the current pull request. Please ensure the workflow file is included so that the automated deployment to GitHub Actions Pages works as intended.

dev-bin/make-release.sh (51-90)

The removal of the documentation generation logic also removes the injection of the release version ($TAG) into the documentation site. Previously, the version was explicitly included in the page metadata and displayed on the site. Since the new Hugo setup mounts README.md directly, this version information is no longer present. If maintaining the version display on the docs site is required, consider passing the version to Hugo (e.g., via a data file or environment variable) during the build process in GitHub Actions.

docs/hugo.toml (1)

The site title has been shortened compared to the previous Jekyll configuration. The old title was more descriptive: mod_maxminddb - an Apache module that allows you to query MaxMind DB files. Consider using the full descriptive title for better SEO and consistency with the previous site design.

title = "mod_maxminddb - an Apache module that allows you to query MaxMind DB files"

docs/layouts/_default/default.html (7-8)

The PR description states that all CSS is inlined to avoid external dependencies, but the current implementation uses a <link> tag to an external stylesheet. To fulfill the stated goal and improve performance for this single-page site, you can inline the minified CSS content directly into a <style> block.

    <style>
      {{- (resources.Get "css/main.css" | resources.Minify).Content | safeCSS -}}
    </style>

docs/layouts/404.html (7-8)

As with the default layout, the CSS here should be inlined to match the PR description and ensure no external requests are made for styles.

    <style>
      {{- (resources.Get "css/main.css" | resources.Minify).Content | safeCSS -}}
    </style>

Extracts the inline `<style>` block from the default and 404 layouts into `docs/assets/css/main.css`, served via Hugo's asset pipeline. Both layouts now reference the file via `<link rel="stylesheet">`, so the 404 page inherits the full stylesheet instead of duplicating a subset of rules. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

gemini-code-assist Bot reviewed May 15, 2026

View reviewed changes

oschwald and others added 3 commits May 18, 2026 23:24

oschwald force-pushed the greg/stf-448 branch from b16c889 to 9a7dded Compare May 18, 2026 23:24

horgh requested changes May 20, 2026

View reviewed changes

oschwald and others added 3 commits May 20, 2026 14:29

oschwald force-pushed the greg/stf-448 branch from 94fd59c to 2963f2e Compare May 20, 2026 14:56

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

Comment thread docs/layouts/404.html Outdated

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

oschwald force-pushed the greg/stf-448 branch from c791575 to 0e6141c Compare May 20, 2026 17:17

horgh approved these changes May 21, 2026

View reviewed changes

horgh merged commit 3a9c928 into main May 21, 2026
7 checks passed

horgh deleted the greg/stf-448 branch May 21, 2026 02:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deploy docs site with Hugo and GitHub Actions#171

Deploy docs site with Hugo and GitHub Actions#171
horgh merged 7 commits into
mainfrom
greg/stf-448

oschwald commented May 15, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot May 15, 2026

Uh oh!

gemini-code-assist Bot May 15, 2026

Uh oh!

horgh May 20, 2026

Uh oh!

oschwald May 20, 2026

Uh oh!

horgh May 20, 2026

Uh oh!

oschwald May 20, 2026

Uh oh!

oschwald commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

oschwald commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,14 @@
		baseURL = "https://maxmind.github.io/mod_maxminddb/"
		title = "mod_maxminddb"

	title = "mod_maxminddb"
	title = "mod_maxminddb - an Apache module that allows you to query MaxMind DB files"

		@@ -0,0 +1,13 @@
		title = "mod_maxminddb"
		disableKinds = ["taxonomy"]

Conversation

oschwald commented May 15, 2026

Summary

Post-merge steps

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 15, 2026

Choose a reason for hiding this comment

Uh oh!

horgh May 20, 2026

Choose a reason for hiding this comment

Uh oh!

oschwald May 20, 2026

Choose a reason for hiding this comment

Uh oh!

horgh May 20, 2026

Choose a reason for hiding this comment

Uh oh!

oschwald May 20, 2026

Choose a reason for hiding this comment

Uh oh!

oschwald commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

oschwald commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

mise.toml (18-24)

dev-bin/make-release.sh (51-90)

docs/hugo.toml (1)

docs/layouts/_default/default.html (7-8)

docs/layouts/404.html (7-8)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants