Deploy docs site with Hugo via GitHub Actions by oschwald · Pull Request #303 · maxmind/GeoIP2-php

oschwald · 2026-05-15T22:44:21Z

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 phpDocumentor output
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/ subtree stays untouched
dev-bin/release.sh no longer regenerates the Jekyll index.md;
the phpDocumentor-publishing block is unchanged

Same design as MaxMind-DB PR #221.

For STF-448.

Post-merge steps

Verify the live site at https://maxmind.github.io/GeoIP2-php/ and
a sample /doc/latest/ still loads after the next workflow run
In a separate commit on gh-pages, drop the legacy Jekyll source
files

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 documentation generation from a manual shell script process to a Hugo-based static site generator. It introduces Hugo configuration, layouts, and mise for tool management. Feedback suggests improving internationalization (i18n) by using site-configured language codes and translation functions instead of hardcoded strings in the HTML templates.

gemini-code-assist · 2026-05-15T22:47:06Z

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


The lang attribute is hardcoded to en. For better accessibility and to support future internationalization (i18n), it is recommended to use the site's configured language code.

Suggested change

<html lang="en">

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

gemini-code-assist · 2026-05-15T22:47:06Z

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


The navigation labels are hardcoded. Following internationalization (i18n) best practices, these strings should be externalized using Hugo's translation features to allow for easier localization in the future.

Suggested change

<a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>Overview</a>

<a href="{{ "doc/latest/" | relURL }}">API documentation</a>

<a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>{{ T "overview" | default "Overview" }}</a>

<a href="{{ "doc/latest/" | relURL }}">{{ T "api_documentation" | default "API documentation" }}</a>

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

/gemini review

gemini-code-assist

Code Review

This pull request transitions the project's documentation from a manual script-based generation to a Hugo static site. Key changes include the addition of a Hugo configuration, custom layouts, and a mise setup for managing the Hugo environment. The release script was updated to remove the legacy index generation logic. Review feedback suggests adding a security configuration to hugo.toml to allow mounting the README.md from the parent directory and notes that the API documentation link may result in a 404 during local development.

gemini-code-assist · 2026-05-18T17:08:14Z

+[[module.mounts]]
+  source = "../README.md"
+  target = "content/_index.md"


Hugo's security model (introduced in version 0.114.0) restricts mounting files from outside the project root by default. Since the build command uses --source docs, the project root is considered the docs/ directory. Mounting ../README.md may fail in strict environments or CI with a security error.

To ensure the build is portable and reliable, consider adding the following security configuration to your hugo.toml:

Suggested change

[[module.mounts]]

source = "../README.md"

target = "content/_index.md"

[security]

[security.module]

mounts = ['^project', '^..']

[[module.mounts]]

source = "../README.md"

target = "content/_index.md"

gemini-code-assist · 2026-05-18T17:08:15Z

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


The link to /doc/latest/ uses relURL, which correctly resolves to the subpath on GitHub Pages. However, because the doc/ directory is managed separately on the gh-pages branch and is not part of the Hugo source or static/ directory, this link will result in a 404 error when previewing the site locally using mise run serve-docs.

While this is expected for the production deployment, you might consider adding a note in the documentation or using a local symlink in docs/static/ (ignored by git) to improve the local development experience.

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/` phpDocumentor 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 phpDocumentor block that builds and publishes `doc/$tag/` 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>

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 fe51a17 to 0f0c50a Compare May 18, 2026 23:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deploy docs site with Hugo via GitHub Actions#303

Deploy docs site with Hugo via GitHub Actions#303
oschwald wants to merge 3 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!

oschwald commented May 18, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot May 18, 2026

Uh oh!

gemini-code-assist Bot May 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

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

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!

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!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant