Skip to content

Deploy docs site with Hugo and GitHub Actions#486

Open
oschwald wants to merge 3 commits into
mainfrom
greg/stf-448
Open

Deploy docs site with Hugo and GitHub Actions#486
oschwald wants to merge 3 commits into
mainfrom
greg/stf-448

Conversation

@oschwald
Copy link
Copy Markdown
Member

Summary

Migrates the docs site at https://maxmind.github.io/geoipupdate/ from
the default Jekyll theme (rendered from main with a bare _config.yml)
to a Hugo build deployed via GitHub Actions. All CSS is inlined in the
layout template — no external CDN dependencies.

  • Hugo site lives under docs/ and mounts README.md as the home page
  • .github/workflows/pages.yml builds with mise run build-docs and
    deploys via the GitHub Actions Pages environment
  • The stale top-level _config.yml is removed

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
    the main branch to GitHub Actions
  2. Verify the site at https://maxmind.github.io/geoipupdate/

Test plan

  • mise run build-docs succeeds with no warnings
  • Rendered <title> and <h1> are correct; CSS is inlined; no
    external CDN references in the output
  • Build job passes in CI (deploy only runs on main)
  • After merge + Terraform apply, verify the live site renders correctly

🤖 Generated with Claude Code

oschwald and others added 3 commits May 15, 2026 22:35
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. CSS is inlined in the layout template with
no external dependencies. Hover any heading to reveal a `#` anchor link.

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 the main branch to
GitHub Actions — handled in the mm_website Terraform PR.

For STF-448.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
With Pages moving to the GitHub Actions workflow that builds the Hugo
docs site, the bare `_config.yml` that previously engaged the default
Jekyll theme is no longer needed.

For STF-448.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown

Modver result

This report was generated by Modver,
a Go package and command that helps you obey semantic versioning rules in your Go module.

This PR does not require a change in your module’s version number.
(You might still consider bumping the patchlevel anyway.)

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a Hugo-based documentation site, including configuration files, layouts, and integration with the mise tool for building and serving the site. Feedback highlights critical issues with the mise.lock file, which contains non-existent tool versions that will cause installation failures. Additionally, the Hugo configuration needs to mount the doc/ directory to ensure that links within the README to external documentation files are not broken.

Comment thread mise.lock
Comment on lines +120 to +122
[[tools.hugo]]
version = "0.161.1"
backend = "aqua:gohugoio/hugo"
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

critical

The versions specified in this lock file (e.g., Hugo 0.161.1, and elsewhere in the file Go 1.26.1 and Node 25.8.0) do not exist in the current ecosystem. It appears these versions were hallucinated by the AI tool used to generate this pull request. This will cause mise install to fail as it won't be able to find these releases. Please regenerate the lock file using the mise lock command in your local environment to capture valid tool versions.

Comment thread docs/hugo.toml
Comment on lines +12 to +14
[[module.mounts]]
source = "../README.md"
target = "content/_index.md"
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The current configuration only mounts the root README.md. However, the README.md contains links to other documentation files located in the doc/ directory (e.g., doc/docker.md, doc/geoipupdate.md). These files will not be included in the Hugo build, resulting in broken links on the deployed documentation site. You should mount the doc/ directory as well to ensure all referenced documentation is available.

Suggested change
[[module.mounts]]
source = "../README.md"
target = "content/_index.md"
[[module.mounts]]
source = "../README.md"
target = "content/_index.md"
[[module.mounts]]
source = "../doc"
target = "content/doc"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant