From 7304efe5b2693a4715df04563b4c257f3dd50570 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 15 May 2026 22:33:40 +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 mounts the existing `doc/libmaxminddb.md` and `doc/mmdblookup.md` as Hugo content so the source of truth stays in one place. A small pill nav lets readers move between the two pages. 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) --- .gitignore | 2 + docs/hugo.toml | 18 ++ .../_default/_markup/render-heading.html | 4 + docs/layouts/_default/default.html | 210 ++++++++++++++++++ mise.lock | 98 ++++++-- mise.toml | 9 + 6 files changed, 322 insertions(+), 19 deletions(-) create mode 100644 docs/hugo.toml create mode 100644 docs/layouts/_default/_markup/render-heading.html create mode 100644 docs/layouts/_default/default.html diff --git a/.gitignore b/.gitignore index d628511e..81f07296 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,8 @@ *~ .\#* .gh-pages +docs/.hugo_build.lock +docs/public/ /INSTALL /autom4te.cache /bin/country_lookup diff --git a/docs/hugo.toml b/docs/hugo.toml new file mode 100644 index 00000000..a6b04fd6 --- /dev/null +++ b/docs/hugo.toml @@ -0,0 +1,18 @@ +baseURL = "https://maxmind.github.io/libmaxminddb/" +title = "libmaxminddb" +disableKinds = ["taxonomy"] + +[[cascade]] + layout = "default" + +[markup.highlight] + noClasses = true + style = "github" + +[[module.mounts]] + source = "../doc/libmaxminddb.md" + target = "content/_index.md" + +[[module.mounts]] + source = "../doc/mmdblookup.md" + target = "content/mmdblookup.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..2e80aa08 --- /dev/null +++ b/docs/layouts/_default/default.html @@ -0,0 +1,210 @@ + + + + + + {{- $title := or .Title .File.BaseFileName -}} + {{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }} + + + + +
+ {{ .Content }} +
+ + diff --git a/mise.lock b/mise.lock index 2fa928ac..601b4edd 100644 --- a/mise.lock +++ b/mise.lock @@ -1,3 +1,5 @@ +# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html + [conda-packages.linux-arm64."linux-aarch64/_openmp_mutex-4.5-3_kmp_llvm"] url = "https://api.anaconda.org/download/conda-forge/_openmp_mutex/4.5/linux-aarch64/_openmp_mutex-4.5-3_kmp_llvm.conda" checksum = "sha256:5ec4d1d1dca8cc57e48132ec795e1df96082a7a69037f07add30d73d388df6ff" @@ -197,7 +199,11 @@ checksum = "sha256:644095227a3dd4559a07ce3f33d660d7e21f5e6b2a4227ce835fa156a4528 [[tools."conda:clang-format"]] version = "21.1.8" backend = "conda:clang-format" -"platforms.linux-arm64" = { checksum = "sha256:f36140c5cfa875bf9981a0fd978c54706227d15c93bedb6fa43c131b7e764b46", conda_deps = [ + +[tools."conda:clang-format"."platforms.linux-arm64"] +checksum = "sha256:f36140c5cfa875bf9981a0fd978c54706227d15c93bedb6fa43c131b7e764b46" +url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/linux-aarch64/clang-format-21.1.8-default_he95a3c9_0.conda" +conda_deps = [ "linux-aarch64/libclang-cpp21.1-21.1.8-default_he95a3c9_0", "linux-aarch64/libgcc-15.2.0-he277a41_5", "linux-aarch64/libzlib-1.3.1-h31becfc_0", @@ -211,8 +217,12 @@ backend = "conda:clang-format" "linux-aarch64/libllvm21-21.1.8-hfd2ba90_0", "linux-aarch64/libxml2-2.15.1-h49afab2_0", "linux-aarch64/clang-format-21-21.1.8-default_he95a3c9_0", -], url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/linux-aarch64/clang-format-21.1.8-default_he95a3c9_0.conda"} -"platforms.linux-x64" = { checksum = "sha256:7dde9b7439f38d239a827f71136f6a172d324fef183fb3ad334efb1701f62f2e", conda_deps = [ +] + +[tools."conda:clang-format"."platforms.linux-x64"] +checksum = "sha256:7dde9b7439f38d239a827f71136f6a172d324fef183fb3ad334efb1701f62f2e" +url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/linux-64/clang-format-21.1.8-default_h99862b1_0.conda" +conda_deps = [ "linux-64/zstd-1.5.7-hb8e6e7a_0", "linux-64/clang-format-21-21.1.8-default_h99862b1_0", "linux-64/libclang-cpp21.1-21.1.8-default_h99862b1_0", @@ -227,8 +237,12 @@ backend = "conda:clang-format" "linux-64/_openmp_mutex-4.5-3_kmp_llvm", "linux-64/libzlib-1.3.1-hd590300_0", "linux-64/libxml2-16-2.15.1-ha9997c6_0", -], url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/linux-64/clang-format-21.1.8-default_h99862b1_0.conda"} -"platforms.macos-arm64" = { checksum = "sha256:f968186fa56331fc1bbe6a5ced9eba08bb50c57e780e3daea863773e8b59d32f", conda_deps = [ +] + +[tools."conda:clang-format"."platforms.macos-arm64"] +checksum = "sha256:f968186fa56331fc1bbe6a5ced9eba08bb50c57e780e3daea863773e8b59d32f" +url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/osx-arm64/clang-format-21.1.8-default_hf3020a7_0.conda" +conda_deps = [ "osx-arm64/libxml2-2.15.1-h9329255_0", "osx-arm64/liblzma-5.8.2-h8088a28_0", "osx-arm64/libcxx-22.1.0.rc2-h919050e_0", @@ -240,8 +254,12 @@ backend = "conda:clang-format" "osx-arm64/clang-format-21-21.1.8-default_hf3020a7_0", "osx-arm64/libclang-cpp21.1-21.1.8-default_hf3020a7_0", "osx-arm64/libiconv-1.18-hfe07756_0", -], url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/osx-arm64/clang-format-21.1.8-default_hf3020a7_0.conda"} -"platforms.macos-x64" = { checksum = "sha256:477805cf0016cfa9738936f76d85970daefee72a1a9f2276df1a34581073b135", conda_deps = [ +] + +[tools."conda:clang-format"."platforms.macos-x64"] +checksum = "sha256:477805cf0016cfa9738936f76d85970daefee72a1a9f2276df1a34581073b135" +url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/osx-64/clang-format-21.1.8-default_hd70426c_0.conda" +conda_deps = [ "osx-64/libzlib-1.3.1-hd75f5a5_0", "osx-64/clang-format-21-21.1.8-default_hd70426c_0", "osx-64/libclang-cpp21.1-21.1.8-default_hd70426c_0", @@ -253,26 +271,68 @@ backend = "conda:clang-format" "osx-64/libllvm21-21.1.8-h56e7563_0", "osx-64/libcxx-22.1.0.rc2-hb6afd73_0", "osx-64/libxml2-2.15.1-h7b7ecba_0", -], url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/osx-64/clang-format-21.1.8-default_hd70426c_0.conda"} -"platforms.windows-x64" = { checksum = "sha256:dd8855c6b01dd986d55b67cef7b9532749493aeebbbb70fdc3f2b6cd348981e0", url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/win-64/clang-format-21.1.8-default_hac490eb_0.conda"} +] + +[tools."conda:clang-format"."platforms.windows-x64"] +checksum = "sha256:dd8855c6b01dd986d55b67cef7b9532749493aeebbbb70fdc3f2b6cd348981e0" +url = "https://api.anaconda.org/download/conda-forge/clang-format/21.1.8/win-64/clang-format-21.1.8-default_hac490eb_0.conda" [[tools."github:houseabsolute/precious"]] version = "0.10.2" backend = "github:houseabsolute/precious" -"platforms.linux-arm64" = { checksum = "sha256:8fbaead9f9626170549c3121e67d1bc81193b3bb086e29576f548aefa839fcc4", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-Linux-musl-arm64.tar.gz", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345520042"} -"platforms.linux-x64" = { checksum = "sha256:3d717d906db338f63017766b07982dc9055773e1b3bec6d3f432d1f0ad9676bb", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-Linux-musl-x86_64.tar.gz", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345519861"} -"platforms.macos-arm64" = { checksum = "sha256:04157c64459bb6ab029295b21b112077040ad2575b34508d84b19a839551cddb", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-macOS-arm64.tar.gz", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345519985"} -"platforms.macos-x64" = { checksum = "sha256:9932defd246d0771530357463bdb55582557fd7381853cb4dc2074e36ad0cc84", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-macOS-x86_64.tar.gz", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345519772"} -"platforms.windows-x64" = { checksum = "sha256:9d683d1730e302c646ccb90a23d313e7a548c8b23b5abf7d24e19ff6befe763d", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-Windows-msvc-x86_64.zip", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345520544"} + +[tools."github:houseabsolute/precious"."platforms.linux-arm64"] +checksum = "sha256:8fbaead9f9626170549c3121e67d1bc81193b3bb086e29576f548aefa839fcc4" +url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-Linux-musl-arm64.tar.gz" +url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345520042" + +[tools."github:houseabsolute/precious"."platforms.linux-x64"] +checksum = "sha256:3d717d906db338f63017766b07982dc9055773e1b3bec6d3f432d1f0ad9676bb" +url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-Linux-musl-x86_64.tar.gz" +url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345519861" + +[tools."github:houseabsolute/precious"."platforms.macos-arm64"] +checksum = "sha256:04157c64459bb6ab029295b21b112077040ad2575b34508d84b19a839551cddb" +url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-macOS-arm64.tar.gz" +url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345519985" + +[tools."github:houseabsolute/precious"."platforms.macos-x64"] +checksum = "sha256:9932defd246d0771530357463bdb55582557fd7381853cb4dc2074e36ad0cc84" +url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-macOS-x86_64.tar.gz" +url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345519772" + +[tools."github:houseabsolute/precious"."platforms.windows-x64"] +checksum = "sha256:9d683d1730e302c646ccb90a23d313e7a548c8b23b5abf7d24e19ff6befe763d" +url = "https://github.com/houseabsolute/precious/releases/download/v0.10.2/precious-Windows-msvc-x86_64.zip" +url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/345520544" + +[[tools.hugo]] +version = "0.161.1" +backend = "aqua:gohugoio/hugo" [[tools.node]] version = "25.6.1" backend = "core:node" -"platforms.linux-arm64" = { checksum = "sha256:90fea701897ecb424aafa2824539476598437ad9f21e649732a85cc2d955d845", url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-linux-arm64.tar.gz"} -"platforms.linux-x64" = { checksum = "sha256:3809fdbfd54829bad363b9db8e96ca3600509e2ff20ede74181cfc1ca8451ce3", url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-linux-x64.tar.gz"} -"platforms.macos-arm64" = { checksum = "sha256:a80cb252d170a4730f78f5950cf19a46106f156e5886e5c1cc8c5602aea60243", url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-darwin-arm64.tar.gz"} -"platforms.macos-x64" = { checksum = "sha256:3b68f847d9d8861c7c8bfef32c540d14f6ca18bfcbf5f6495a595b9529063a9b", url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-darwin-x64.tar.gz"} -"platforms.windows-x64" = { checksum = "sha256:0ae2300cdf44c399b5b351edbefb3534d1342a6fabd64302ca8c8e2fb86b0445", url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-win-x64.zip"} + +[tools.node."platforms.linux-arm64"] +checksum = "sha256:90fea701897ecb424aafa2824539476598437ad9f21e649732a85cc2d955d845" +url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-linux-arm64.tar.gz" + +[tools.node."platforms.linux-x64"] +checksum = "sha256:3809fdbfd54829bad363b9db8e96ca3600509e2ff20ede74181cfc1ca8451ce3" +url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-linux-x64.tar.gz" + +[tools.node."platforms.macos-arm64"] +checksum = "sha256:a80cb252d170a4730f78f5950cf19a46106f156e5886e5c1cc8c5602aea60243" +url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-darwin-arm64.tar.gz" + +[tools.node."platforms.macos-x64"] +checksum = "sha256:3b68f847d9d8861c7c8bfef32c540d14f6ca18bfcbf5f6495a595b9529063a9b" +url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-darwin-x64.tar.gz" + +[tools.node."platforms.windows-x64"] +checksum = "sha256:0ae2300cdf44c399b5b351edbefb3534d1342a6fabd64302ca8c8e2fb86b0445" +url = "https://nodejs.org/dist/v25.6.1/node-v25.6.1-win-x64.zip" [[tools."npm:prettier"]] version = "3.8.1" diff --git a/mise.toml b/mise.toml index 83e93536..ba199c03 100644 --- a/mise.toml +++ b/mise.toml @@ -8,7 +8,16 @@ disable_backends = [ ] [tools] +hugo = "latest" node = "latest" "pipx:clang-format" = "21.1.8" "github:houseabsolute/precious" = "latest" "npm:prettier" = "latest" + +[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 22b0ac2891f9afbe7804194d4aedd15398e68f1e Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 15 May 2026 22:34:09 +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 b10d8ca06120ac7a5dc10a6f06a8fc50bc4ce55a Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 15 May 2026 22:34:29 +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 Jekyll index/mmdblookup pages — the new Hugo workflow on main owns the docs site, and the doc/*.md files are now mounted as content directly. There is no versioned doc tree on gh-pages to preserve for this repo. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) --- .gitignore | 1 - dev-bin/release.sh | 43 ------------------------------------------- 2 files changed, 44 deletions(-) diff --git a/.gitignore b/.gitignore index 81f07296..1e9ab789 100644 --- a/.gitignore +++ b/.gitignore @@ -8,7 +8,6 @@ */.libs *~ .\#* -.gh-pages docs/.hugo_build.lock docs/public/ /INSTALL diff --git a/dev-bin/release.sh b/dev-bin/release.sh index 4e949c49..258fad2a 100755 --- a/dev-bin/release.sh +++ b/dev-bin/release.sh @@ -111,45 +111,6 @@ make check make clean make safedist -if [ ! -d .gh-pages ]; then - echo "Checking out gh-pages in .gh-pages" - git clone -b gh-pages git@github.com:maxmind/libmaxminddb.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: libmaxminddb - a library for working with MaxMind DB files -version: $version ---- -EOF - -cat ../doc/libmaxminddb.md >>$index - -mmdblookup=mmdblookup.md -cat <$mmdblookup ---- -layout: default -title: mmdblookup - a utility to look up an IP address in a MaxMind DB file -version: $version ---- -EOF - -cat ../doc/mmdblookup.md >>$mmdblookup - -git commit -m "Updated for $version" -a - read -r -e -p "Push to origin? (y/n) " should_push if [ "$should_push" != "y" ]; then @@ -159,8 +120,4 @@ fi git push -popd - -git push - gh release create --target "$(git branch --show-current)" -t "$version" -n "$notes" "$version" "$dist"