Deploy docs site with Hugo via GitHub Actions by oschwald · Pull Request #374 · maxmind/MaxMind-DB-Reader-java

oschwald · 2026-05-15T22:41:36Z

Summary

Migrates the Pages index from Jekyll on gh-pages to a Hugo build that
publishes back onto gh-pages from GitHub Actions. All CSS is now
inlined in the layout template — no external CDN dependencies.

Hugo site lives under docs/ on main and mounts README.md as the
home page
A small pill nav links from the overview to the Javadoc at
/doc/latest/
.github/workflows/pages.yml builds with mise run build-docs and
pushes to gh-pages via peaceiris/actions-gh-pages with
keep_files: true, so every /doc/vX.Y.Z/ Javadoc subtree stays
untouched
dev-bin/release.sh no longer regenerates the Jekyll index.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

Verify the live site at https://maxmind.github.io/MaxMind-DB-Reader-java/
and a sample /doc/latest/ still loads after the next workflow run
In a separate commit on gh-pages, drop the legacy Jekyll source
(_config.yml, _layouts/, the release-generated index.md,
stylesheets/pygments.css, Gemfile*)

Pages source stays on gh-pages — no Terraform change for this repo.

Test plan

mise run build-docs succeeds with no warnings
Rendered <title>, <h1>, and pill nav are correct
No static-gh.maxmind.com references in the new site
Build job passes in CI (push step only runs on main)
After merge, confirm the workflow pushes successfully to gh-pages
and /doc/vX.Y.Z/ subtrees are preserved

🤖 Generated with Claude Code

gemini-code-assist

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.

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


+[tasks.build-docs]
+description = "Build the docs site with Hugo"
+run = "hugo --source docs --minify"


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.

Suggested change

run = "hugo --source docs --minify"

run = "hugo --source docs --minify --cleanDestinationDir"

oschwald · 2026-05-18T17:06:04Z

/gemini review

gemini-code-assist

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.

gemini-code-assist · 2026-05-18T17:07:52Z

@@ -0,0 +1,207 @@
+<!doctype html>
+<html lang="en">


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.

Suggested change

<html lang="en">

<html lang="{{ .Site.LanguageCode | default 'en' }}">

gemini-code-assist · 2026-05-18T17:07:52Z

+      <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active" aria-current="page"{{ end }}>Overview</a>
+      <a href="{{ "/doc/latest/" | relURL }}">API documentation</a>


The navigation labels "Overview" and "API documentation" are hardcoded in English. For better maintainability and future internationalization support, consider using Hugo's i18n function.

gemini-code-assist · 2026-05-18T17:07:52Z

@@ -0,0 +1,4 @@
+<h{{ .Level }} id="{{ .Anchor }}">
+  {{- .Text | safeHTML -}}
+  <a class="heading-anchor" href="#{{ .Anchor }}" aria-label="Link to {{ .PlainText }}">#</a>


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>

horgh · 2026-05-20T02:30:24Z

+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/public
+          publish_branch: gh-pages
+          keep_files: true


Same comment as on the minfraud-api-java PR.

Same as on the GeoIP2-java PR: deferred to post-merge, captured on the Linear STF-448 cleanup checklist (one-time direct push to gh-pages after Hugo populates the new content).

(Claude, responding on behalf of @oschwald.)

horgh · 2026-05-20T02:31:03Z

+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: true


Same comment as on the minfraud-api-java PR.

Addressed in 9b2df39 — persist-credentials: false. Same fix as on the GeoIP2-java PR.

(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>

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

/gemini review

gemini-code-assist

Code Review

This pull request migrates the project documentation to a Hugo-based static site, adding the necessary configuration, layouts, and build tasks while removing the previous manual release script logic. A review comment identifies a missing baseURL in the Hugo configuration, which is essential for correct link resolution when the site is deployed to GitHub Pages.

gemini-code-assist · 2026-05-20T15:17:49Z

@@ -0,0 +1,13 @@
+title = "MaxMind DB Java API"


The baseURL is missing from the Hugo configuration. Since the documentation site is hosted on GitHub Pages at a subpath (/MaxMind-DB-Reader-java/), Hugo requires a baseURL to correctly resolve relative links and asset paths. Without it, the relURL function used in the navigation (line 208 of default.html) and .RelPermalink will generate paths relative to the domain root (e.g., /doc/latest/), which will result in 404 errors on the deployed site. While hugo server handles this correctly during local development, the production build will be broken.

Suggested change

title = "MaxMind DB Java API"

baseURL = "https://maxmind.github.io/MaxMind-DB-Reader-java/"

title = "MaxMind DB Java API"

baseURL was deliberately removed from hugo.toml in an earlier round of this PR. It's now passed via the HUGO_BASEURL env var in the workflow's "Build docs" step, which Hugo natively supports as a config override. The deployed link generation is correct.

(Claude, responding on behalf of @oschwald.)

`.File` is nil on virtual pages (e.g., taxonomy listings before they were disabled). Wrap with `with .File` so the title rendering is null-safe even if future virtual pages get enabled. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

peaceiris/actions-gh-pages uses its own `github_token` input for the push to gh-pages; the credentials persisted by `actions/checkout` aren't read. Setting `persist-credentials: false` matches the rest of the workflows in this repo and silences zizmor's `artipacked` rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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

/gemini review

gemini-code-assist

Code Review

This pull request migrates the project's documentation from a manually generated GitHub Pages file to a Hugo-based site. It introduces a new Hugo configuration, CSS styles, and layout templates, while updating the release script and environment configuration (mise) to support the new build process. Feedback highlights the necessity of adding a baseURL to the Hugo configuration for correct asset resolution on GitHub Pages and suggests inlining and minifying CSS within the HTML templates to improve performance and consistency with the PR's objectives.

gemini-code-assist · 2026-05-20T16:56:42Z

@@ -0,0 +1,13 @@
+title = "MaxMind DB Java API"


The baseURL is missing from the Hugo configuration. When deploying to GitHub Pages as a project site (which resides in a subdirectory like /MaxMind-DB-Reader-java/), Hugo needs the baseURL to correctly resolve relative URLs and asset paths. Without it, links generated via relURL or RelPermalink will point to the root of the domain (e.g., maxmind.github.io/doc/latest/) instead of the project subdirectory, leading to 404 errors.

Suggested change

title = "MaxMind DB Java API"

baseURL = "https://maxmind.github.io/MaxMind-DB-Reader-java/"

title = "MaxMind DB Java API"

baseURL was deliberately removed from hugo.toml in an earlier round of this PR. It's passed via the HUGO_BASEURL env var in the workflow's "Build docs" step (Hugo natively respects this as a config override). The deployed link generation is correct.

(Claude, responding on behalf of @oschwald.)

gemini-code-assist · 2026-05-20T16:56:42Z

+    {{- $css := resources.Get "css/main.css" -}}
+    <link rel="stylesheet" href="{{ $css.RelPermalink }}" />


The PR description states that "All CSS is now inlined in the layout template", but the current implementation uses a <link> tag. To actually inline the CSS and avoid an extra network request, you can use Hugo's resources.Get combined with .Content. This also allows you to minify the CSS during the build process.

Suggested change

{{- $css := resources.Get "css/main.css" -}}

<link rel="stylesheet" href="{{ $css.RelPermalink }}" />

{{- $css := resources.Get "css/main.css" | minify -}}

<style>{{ $css.Content | safeCSS }}</style>

The PR description is stale — externalizing the CSS in round 9 was a deliberate choice on top of the earlier inlined form, made to enable browser caching of the stylesheet across pages on the docs site. The code is doing what we want; we'll update the PR description to reflect the current state.

(Claude, responding on behalf of @oschwald.)

gemini-code-assist · 2026-05-20T16:56:42Z

+    {{- $css := resources.Get "css/main.css" -}}
+    <link rel="stylesheet" href="{{ $css.RelPermalink }}" />


Similar to the default layout, the CSS here is linked rather than inlined as stated in the PR description. Inlining it here ensures consistency and optimal performance for the 404 page.

Suggested change

{{- $css := resources.Get "css/main.css" -}}

<link rel="stylesheet" href="{{ $css.RelPermalink }}" />

{{- $css := resources.Get "css/main.css" | minify -}}

<style>{{ $css.Content | safeCSS }}</style>

The PR description is stale — externalizing the CSS in round 9 was a deliberate choice on top of the earlier inlined form, made to enable browser caching of the stylesheet across pages on the docs site. The code is doing what we want; we'll update the PR description to reflect the current state.

(Claude, responding on behalf of @oschwald.)

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

gemini-code-assist Bot reviewed May 18, 2026

View reviewed changes

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

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

horgh requested changes May 20, 2026

View reviewed changes

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

oschwald force-pushed the greg/stf-448 branch from 9b2df39 to 8e704cf Compare May 20, 2026 14:56

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

oschwald and others added 2 commits May 20, 2026 16:10

oschwald force-pushed the greg/stf-448 branch from 8e704cf to 4e29b11 Compare May 20, 2026 16:10

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

oschwald force-pushed the greg/stf-448 branch from 4e29b11 to a87aed6 Compare May 20, 2026 17:17

	run = "hugo --source docs --minify"
	run = "hugo --source docs --minify --cleanDestinationDir"

	<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>

	title = "MaxMind DB Java API"
	baseURL = "https://maxmind.github.io/MaxMind-DB-Reader-java/"
	title = "MaxMind DB Java API"

		{{- $css := resources.Get "css/main.css" -}}
		<link rel="stylesheet" href="{{ $css.RelPermalink }}" />

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!

oschwald commented May 18, 2026

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 18, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 18, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 18, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

gemini-code-assist Bot May 20, 2026

Choose a reason for hiding this comment

Uh oh!

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!

gemini-code-assist Bot May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants