From 1b223321e10124f4f27bc32bbd57bcf9fdeba5b2 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 15 May 2026 22:23:47 +0000 Subject: [PATCH 1/3] Add Hugo-based docs site MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Build with `mise run build-docs`, preview with `mise run serve-docs`. The site renders the README as the home page via a module mount; CSS is inlined in the layout template with no external dependencies. Hover any heading to reveal a `#` anchor link. Charter serif body text, forest-green accent on field-name headings — same design as the MaxMind-DB spec site. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) --- .gitignore | 2 + docs/hugo.toml | 14 ++ .../_default/_markup/render-heading.html | 4 + docs/layouts/_default/default.html | 172 ++++++++++++++++++ mise.toml | 24 +++ 5 files changed, 216 insertions(+) create mode 100644 docs/hugo.toml create mode 100644 docs/layouts/_default/_markup/render-heading.html create mode 100644 docs/layouts/_default/default.html create mode 100644 mise.toml diff --git a/.gitignore b/.gitignore index 3c6ce62e..ab8a616d 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,8 @@ *.so.* *.sw? .gh-pages +docs/.hugo_build.lock +docs/public/ .libs .tidyall.d MYMETA.json diff --git a/docs/hugo.toml b/docs/hugo.toml new file mode 100644 index 00000000..0069cf29 --- /dev/null +++ b/docs/hugo.toml @@ -0,0 +1,14 @@ +baseURL = "https://maxmind.github.io/mod_maxminddb/" +title = "mod_maxminddb" +disableKinds = ["taxonomy"] + +[[cascade]] + layout = "default" + +[markup.highlight] + noClasses = true + style = "github" + +[[module.mounts]] + source = "../README.md" + target = "content/_index.md" diff --git a/docs/layouts/_default/_markup/render-heading.html b/docs/layouts/_default/_markup/render-heading.html new file mode 100644 index 00000000..4f4fcc0a --- /dev/null +++ b/docs/layouts/_default/_markup/render-heading.html @@ -0,0 +1,4 @@ + + {{- .Text | safeHTML -}} + # + diff --git a/docs/layouts/_default/default.html b/docs/layouts/_default/default.html new file mode 100644 index 00000000..324df8fb --- /dev/null +++ b/docs/layouts/_default/default.html @@ -0,0 +1,172 @@ + + + + + + {{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ .Title }} | {{ .Site.Title }}{{ end }} + + + +
+ {{ .Content }} +
+ + diff --git a/mise.toml b/mise.toml new file mode 100644 index 00000000..ecc66982 --- /dev/null +++ b/mise.toml @@ -0,0 +1,24 @@ +[settings] +lockfile = true +disable_backends = [ + "asdf", + "vfox", +] + +[tools] +hugo = "latest" + +[hooks] +enter = "mise install --quiet" + +[[watch_files]] +patterns = ["mise.toml", "mise.lock"] +run = "mise install --quiet" + +[tasks.build-docs] +description = "Build the docs site with Hugo" +run = "hugo --source docs --minify" + +[tasks.serve-docs] +description = "Serve the docs site locally with Hugo dev server" +run = "hugo server --source docs" From 0a563a507184099a5b2d5a202b1710205f1d8770 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 15 May 2026 22:24:30 +0000 Subject: [PATCH 2/3] Add GitHub Pages deployment workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 "Deploy from a branch" (gh-pages) to "GitHub Actions" — handled in the mm_website Terraform PR. The legacy gh-pages branch can then be deleted. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/pages.yml | 52 +++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 .github/workflows/pages.yml diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 00000000..89e278f8 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,52 @@ +name: Deploy to GitHub Pages + +on: + push: + branches: ["main"] + workflow_dispatch: + +permissions: {} + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + + - name: Setup mise + uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8 # v3.6.1 + with: + cache: true + + - name: Build docs + run: mise run build-docs + + - name: Configure Pages + uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0 + + - name: Upload artifact + uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0 + with: + path: docs/public + + deploy: + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5 From a8857b3cd57e530525db8d6dcbd62839b31a527d Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 15 May 2026 22:25:25 +0000 Subject: [PATCH 3/3] Remove gh-pages publishing from release script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The release script no longer needs to clone the gh-pages branch and regenerate a Jekyll index page from README.md — the new Hugo workflow on main owns the docs site, and there is no versioned doc tree on gh-pages for this repo to preserve. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) --- .gitignore | 1 - dev-bin/make-release.sh | 41 ----------------------------------------- 2 files changed, 42 deletions(-) diff --git a/.gitignore b/.gitignore index ab8a616d..abf75b2d 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,6 @@ *.so *.so.* *.sw? -.gh-pages docs/.hugo_build.lock docs/public/ .libs diff --git a/dev-bin/make-release.sh b/dev-bin/make-release.sh index 07201c02..2888e67c 100755 --- a/dev-bin/make-release.sh +++ b/dev-bin/make-release.sh @@ -48,46 +48,5 @@ git commit -m "Bumped version to $TAG" ./configure make dist -if [ ! -d .gh-pages ]; then - echo "Checking out gh-pages in .gh-pages" - git clone -b gh-pages git@github.com:maxmind/mod_maxminddb.git .gh-pages - pushd .gh-pages -else - echo "Updating .gh-pages" - pushd .gh-pages - git pull -fi - -if [ -n "$(git status --porcelain)" ]; then - echo ".gh-pages is not clean" >&2 - exit 1 -fi - -INDEX=index.md -cat < $INDEX ---- -layout: default -title: mod_maxminddb - an Apache module that allows you to query MaxMind DB files -version: $TAG ---- -EOF - -cat ../README.md >> $INDEX - -if [ -n "$(git status --porcelain)" ]; then - git commit -m "Updated for $TAG" -a - - read -p "Push to origin? (yN) " SHOULD_PUSH - - if [ "$SHOULD_PUSH" != "y" ]; then - echo "Aborting" - exit 1 - fi - - git push -fi - -popd - git tag -a -m "Release for $TAG" $TAG git push --follow-tags