Deploy docs site with Hugo and GitHub Actions

[oschwald]

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 and mounts the existing
  doc/libmaxminddb.md and doc/mmdblookup.md as content, keeping the
  source of truth in one place
• A small pill nav at the top of each page lets readers move between the
  two docs
• .github/workflows/pages.yml builds with mise run build-docs and
  deploys via the GitHub Actions Pages environment
• dev-bin/release.sh no longer clones gh-pages or regenerates the
  index/mmdblookup Jekyll pages

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

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

Test plan

• mise run build-docs succeeds with no warnings
• Both index.html and mmdblookup/index.html render with correct
  titles and working pill-nav
• grep -r static-gh docs/ returns nothing
• 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 documentation from Jekyll to Hugo. It removes the manual documentation generation logic from the release script, adds Hugo configuration and layouts, and introduces mise tasks for building and serving the site. Review feedback focuses on refining the Hugo implementation, specifically restoring descriptive page titles lost during the migration, improving title tag logic, utilizing link titles in navigation, and pinning the Hugo version in the configuration for better build reproducibility.

[gemini-code-assist]

The migration to Hugo has resulted in the loss of descriptive page titles that were previously provided in the Jekyll front matter. Currently, Hugo defaults to using the filename (e.g., "mmdblookup") as the title. You can restore the descriptive titles (and optionally provide shorter link titles for the navigation) using Hugo's cascade feature in the configuration file.

Suggested change

	[[cascade]]
	layout = "default"
	[[cascade]]
	layout = "default"
	[[cascade]]
	[cascade._target]
	path = "/_index.md"
	title = "libmaxminddb - a library for working with MaxMind DB files"
	linkTitle = "libmaxminddb"
	[[cascade]]
	[cascade._target]
	path = "/mmdblookup.md"
	title = "mmdblookup - a utility to look up an IP address in a MaxMind DB file"
	linkTitle = "mmdblookup"

[gemini-code-assist]

To support descriptive titles for the home page (set via configuration or front matter), the title tag should check for .Title before falling back to .Site.Title.

Suggested change

	<title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>
	<title>{{ if .IsHome }}{{ or .Title .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>

[gemini-code-assist]

Using .LinkTitle in the navigation allows for shorter labels in the pill nav while maintaining descriptive titles for the browser tab. This works in conjunction with the cascade settings in hugo.toml.

Suggested change

	<a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>{{ .Site.Title }}</a>
	{{ range .Site.RegularPages }}
	<a href="{{ .RelPermalink }}"{{ if eq $.RelPermalink .RelPermalink }} class="active"{{ end }}>{{ or .Title .File.BaseFileName }}</a>
	{{ end }}
	<a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>{{ or .Site.Home.LinkTitle .Site.Title }}</a>
	{{ range .Site.RegularPages }}
	<a href="{{ .RelPermalink }}"{{ if eq $.RelPermalink .RelPermalink }} class="active"{{ end }}>{{ or .LinkTitle .Title .File.BaseFileName }}</a>
	{{ end }}

[gemini-code-assist]

It is recommended to pin the Hugo version to a specific version (e.g., the one currently in the lock file) to ensure build reproducibility across different environments and CI. Using latest can lead to unexpected build failures if a new version of Hugo introduces breaking changes.

Suggested change

	hugo = "latest"
	hugo = "0.161.1"

[oschwald]

/gemini review

[gemini-code-assist]

Code Review

This pull request migrates the documentation site from Jekyll to Hugo, introducing a new Hugo configuration, base templates, and styling. The release.sh script was simplified by removing the manual documentation generation and deployment logic. Feedback suggests restoring the version information in the documentation which was lost during the migration and improving the home page title for better SEO and clarity.

[gemini-code-assist]

The migration to Hugo removes the logic that previously injected the library version into the documentation site. In the Jekyll setup, release.sh added a version field to the front matter. Since the new Hugo site mounts raw markdown files from ../doc/, this version information is no longer present in the rendered site. Consider passing the version as a Hugo parameter or environment variable during the build process in GitHub Actions and updating the template to display it.

[gemini-code-assist]

The home page title is currently set to the site title ("libmaxminddb"), which is less descriptive than the previous Jekyll title ("libmaxminddb - a library for working with MaxMind DB files"). This can affect SEO and browser tab clarity. Consider using the more descriptive title for the home page.

Suggested change

	<title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>
	<title>{{ if .IsHome }}libmaxminddb - a library for working with MaxMind DB files{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>

[horgh]

From Claude. Not sure if it matters if it's right:

  - URL path break. Old Jekyll used permalink: /:title.html → mmdblookup.html. Hugo pretty URLs → /mmdblookup/. External links (forums, SO, blogs) to mmdblookup.html will 404.
  Fix: set permalinks in hugo.toml or add aliases frontmatter on each page.

[oschwald]

Addressed in 889b63c — added uglyURLs = true to hugo.toml. Old Jekyll served /mmdblookup.html via permalink: /:title.html; with uglyURLs Hugo emits the same .html suffix on non-home pages, so existing external links resolve unchanged.

(Claude, responding on behalf of @oschwald.)

[horgh]

Same feedback as on geoipupdate PR.

[oschwald]

Addressed in b284fb1 — disableKinds = ["taxonomy", "term", "RSS"].

(Claude, responding on behalf of @oschwald.)

[oschwald]

/gemini review

[gemini-code-assist]

Code Review

This pull request migrates the project's documentation system from a manual shell script process to a Hugo-based static site generator. The changes include removing legacy documentation generation from the release script, adding Hugo configuration and layouts, and updating the project's tool configuration to include Hugo and documentation-related tasks. A review comment identified a bug in the Hugo template logic where variable scoping prevented the correct assignment of page titles; a simplified approach using the 'or' function was suggested to resolve this.

[oschwald]

/gemini review

[gemini-code-assist]

Code Review

This pull request migrates the documentation generation process from a manual shell script in release.sh to a Hugo-based static site generator. It introduces a new docs directory containing Hugo configurations, layout templates, and CSS, while updating project tooling via mise to include Hugo tasks. Review feedback points out that uglyURLs should be disabled to maintain standard directory-style URL structures and suggests inlining the CSS to align with the PR's stated goals and optimize performance.

[gemini-code-assist]

The uglyURLs = true setting causes Hugo to generate files like mmdblookup.html instead of the directory-style structure (mmdblookup/index.html) expected by the test plan and mentioned in the PR description. To maintain the desired URL structure and match the test plan, this should be set to false (which is the default).

Suggested change

	uglyURLs = true
	uglyURLs = false

[oschwald]

The uglyURLs = true setting is deliberate — the pre-migration Jekyll site served mmdblookup.html (the URL pattern documented in external references and search-engine indexed). Switching to Hugo's pretty-URL form (mmdblookup/) would 404 those existing links. This is preserving backward compatibility for libmaxminddb specifically.

(Claude, responding on behalf of @oschwald.)

[gemini-code-assist]

The PR description states that "All CSS is now inlined in the layout template", but the current implementation uses a <link> tag to an external stylesheet. To actually inline the CSS as described and avoid an extra network request, you can use Hugo's .Content property within a <style> tag.

    {{- with resources.Get "css/main.css" | minify -}}
    <style>{{ .Content | safeCSS }}</style>
    {{- end -}}

[oschwald]

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