Deploy docs site with Hugo via GitHub Actions#303
Open
oschwald wants to merge 3 commits into
Open
Conversation
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]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
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.
| @@ -0,0 +1,207 @@ | |||
| <!doctype html> | |||
| <html lang="en"> | |||
There was a problem hiding this comment.
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" }}"> |
Comment on lines
+200
to
+201
| <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>Overview</a> | ||
| <a href="{{ "doc/latest/" | relURL }}">API documentation</a> |
There was a problem hiding this comment.
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> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrates the Pages index from Jekyll on
gh-pagesto a Hugo build thatpublishes back onto
gh-pagesfrom GitHub Actions. All CSS is nowinlined in the layout template — no external CDN dependencies.
docs/onmainand mountsREADME.mdas thehome page
at
/doc/latest/.github/workflows/pages.ymlbuilds withmise run build-docsandpushes to
gh-pagesviapeaceiris/actions-gh-pageswithkeep_files: true, so every/doc/vX.Y.Z/subtree stays untoucheddev-bin/release.shno longer regenerates the Jekyllindex.md;the phpDocumentor-publishing block is unchanged
Same design as MaxMind-DB PR #221.
For STF-448.
Post-merge steps
a sample
/doc/latest/still loads after the next workflow rungh-pages, drop the legacy Jekyll sourcefiles
Pages source stays on
gh-pages— no Terraform change for this repo.Test plan
mise run build-docssucceeds with no warnings<title>,<h1>, and pill nav are correctstatic-gh.maxmind.comreferences in the new sitemain)and
/doc/vX.Y.Z/subtrees are preserved🤖 Generated with Claude Code