Skip to content

Derive Hugo baseURL from GitHub Actions context#240

Open
oschwald wants to merge 5 commits into
mainfrom
greg/hugo-baseurl-from-actions-context
Open

Derive Hugo baseURL from GitHub Actions context#240
oschwald wants to merge 5 commits into
mainfrom
greg/hugo-baseurl-from-actions-context

Conversation

@oschwald
Copy link
Copy Markdown
Member

Summary

Drops the hardcoded baseURL = "https://maxmind.github.io/MaxMind-DB/" from
docs/hugo.toml and instead derives it at build time from GitHub Actions
context variables. The URL is fully determined by the repo identity
(https://<owner>.github.io/<name>/), so duplicating it in config was
busywork — and it also broke for forks and would block any future move to
a custom domain.

  • docs/hugo.tomlbaseURL line removed
  • .github/workflows/pages.ymlHUGO_BASEURL env var added on the
    Build docs step, derived from ${{ github.repository_owner }} and
    ${{ github.event.repository.name }}

Follows Hugo's own GitHub Actions deploy example.

The same pattern is being applied as fixup commits to the sibling repos
in flight for STF-448.

Test plan

  • mise run build-docs succeeds locally without HUGO_BASEURL set
    (Hugo defaults to http://localhost/ — fine for local testing,
    since we don't use sitemap/RSS/OG tags)
  • Rendered <title> and <h1> correct
  • Build job passes in CI (deploy only runs on main)
  • After merge, https://maxmind.github.io/MaxMind-DB/ still renders

🤖 Generated with Claude Code

Instead of hardcoding the GitHub Pages URL in `docs/hugo.toml`, set it
as a step-level `HUGO_BASEURL` env var on the Build docs step in the
deploy workflow. The URL is derived from `github.repository_owner` and
`github.event.repository.name`, so the same workflow continues to work
unchanged if the repo is forked or renamed.

Local builds (e.g., `mise run build-docs`) without `HUGO_BASEURL` set
will use Hugo's default of `http://localhost/`. `mise run serve-docs`
unaffected — the dev server overrides baseURL anyway.

Follows Hugo's own GitHub Actions deploy example:
https://gohugo.io/host-and-deploy/host-on-github-pages/

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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 removes the hardcoded baseURL from docs/hugo.toml. The reviewer identified that this change is incomplete because the corresponding update to the .github/workflows/pages.yml file is missing, which will cause the production site to use an incorrect base URL and break absolute links and asset paths.

Comment thread docs/hugo.toml
@@ -1,4 +1,3 @@
baseURL = "https://maxmind.github.io/MaxMind-DB/"
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 pull request description states that .github/workflows/pages.yml was updated to set the HUGO_BASEURL environment variable, but that file is missing from the changes in this PR. Removing the hardcoded baseURL without the corresponding workflow update will cause the production build to use the default http://localhost/, which will break absolute links and asset paths on the deployed site (especially since it is hosted at a subpath /MaxMind-DB/). Please ensure the workflow changes are included in this pull request.

oschwald and others added 3 commits May 18, 2026 19:06
Defensive `img { max-width: 100%; height: auto; }` so any image rendered
inside the docs content stays within the body's `max-width: 50rem` and
scales on narrow viewports. No images today, but worth shipping in any
layout we use as a template for sibling repos.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`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 oschwald force-pushed the greg/hugo-baseurl-from-actions-context branch from ea393f6 to 45e5370 Compare May 20, 2026 14:56
@oschwald
Copy link
Copy Markdown
Member Author

/gemini review

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 updates the Hugo configuration by removing the hardcoded baseURL and disabling additional page kinds. It also introduces a custom 404 error page and adds responsive image styling to the default layout. A review comment suggests refactoring the new 404 page to use Hugo base templates or partials to reduce code duplication and improve the maintainability of the site's styling.

Comment thread docs/layouts/404.html
@oschwald
Copy link
Copy Markdown
Member Author

/gemini review

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 externalizes the CSS from the default layout into a dedicated stylesheet, adds a custom 404 error page, and updates the Hugo configuration to disable 'term' and 'RSS' page types. The reviewer recommends improving the resource loading logic in the HTML templates by using the with statement to prevent build failures if the CSS file is missing and applying the fingerprint filter to enable cache busting and Subresource Integrity (SRI) for better security.

Comment thread docs/layouts/_default/default.html Outdated
Comment thread docs/layouts/404.html Outdated
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>
@oschwald oschwald force-pushed the greg/hugo-baseurl-from-actions-context branch from c332935 to cdbf330 Compare May 20, 2026 17:17
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