maxmind · oschwald · May 15, 2026 · May 15, 2026 · May 15, 2026 · gemini-code-assist
diff --git a/.github/workflows/pages.yml 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
diff --git a/.gitignore b/.gitignore
@@ -8,7 +8,8 @@
 */.libs
 *~
 .\#*
-.gh-pages
+docs/.hugo_build.lock
+docs/public/
 /INSTALL
 /autom4te.cache
 /bin/country_lookup

diff --git 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 <<EOF >$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 <<EOF >$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"
diff --git a/docs/hugo.toml b/docs/hugo.toml
@@ -0,0 +1,18 @@
+baseURL = "https://maxmind.github.io/libmaxminddb/"
+title = "libmaxminddb"
+disableKinds = ["taxonomy"]
+
+[[cascade]]
+  layout = "default"
-[[cascade]]
-  layout = "default"
+[[cascade]]
+  layout = "default"
+
+[[cascade]]
+  [cascade._target]
+    path = "/_index.md"
+  title = "libmaxminddb - a library for working with MaxMind DB files"
+  linkTitle = "libmaxminddb"
+
+[[cascade]]
+  [cascade._target]
+    path = "/mmdblookup.md"
+  title = "mmdblookup - a utility to look up an IP address in a MaxMind DB file"
+  linkTitle = "mmdblookup"
-[[cascade]]
-  layout = "default"
+[[cascade]]
+  layout = "default"
+
+[[cascade]]
+  [cascade._target]
+    path = "/_index.md"
+  title = "libmaxminddb - a library for working with MaxMind DB files"
+  linkTitle = "libmaxminddb"
+
+[[cascade]]
+  [cascade._target]
+    path = "/mmdblookup.md"
+  title = "mmdblookup - a utility to look up an IP address in a MaxMind DB file"
+  linkTitle = "mmdblookup"
+
+[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
@@ -0,0 +1,4 @@
+<h{{ .Level }} id="{{ .Anchor }}">
+  {{- .Text | safeHTML -}}
+  <a class="heading-anchor" href="#{{ .Anchor }}" aria-label="Link to {{ .PlainText }}">#</a>
+</h{{ .Level }}>
diff --git a/docs/layouts/_default/default.html b/docs/layouts/_default/default.html
@@ -0,0 +1,210 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {{- $title := or .Title .File.BaseFileName -}}
+    <title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>
-    <title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>
+    <title>{{ if .IsHome }}{{ or .Title .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>
-    <title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>
+    <title>{{ if .IsHome }}{{ or .Title .Site.Title }}{{ else }}{{ $title }} | {{ .Site.Title }}{{ end }}</title>
+    <style>
+      :root {
+        --fg: #2d2d2d;
+        --bg: #faf9f7;
+        --accent: #1a6b50;
+        --accent-soft: rgba(26, 107, 80, 0.06);
+        --border: #d5d0c8;
+        --code-bg: #f0eeea;
+        --heading: #1a1a1a;
+        --muted: #70695f;
+      }
+
+      ::selection {
+        background: rgba(26, 107, 80, 0.15);
+      }
+
+      *,
+      *::before,
+      *::after {
+        box-sizing: border-box;
+      }
+
+      body {
+        font-family: Charter, "Bitstream Charter", "Sitka Text", Cambria, serif;
+        font-size: 1.05rem;
+        line-height: 1.78;
+        color: var(--fg);
+        background: var(--bg);
+        max-width: 50rem;
+        margin: 0 auto;
+        padding: 3rem 1.5rem 5rem;
+      }
+
+      h1,
+      h2,
+      h3,
+      h4 {
+        font-family: system-ui, -apple-system, "Segoe UI", Helvetica, Arial,
+          sans-serif;
+        line-height: 1.35;
+      }
+
+      h1 {
+        font-size: 1.75rem;
+        font-weight: 800;
+        color: var(--heading);
+        margin: 0 0 1.5rem;
+        padding-bottom: 0.75rem;
+        border-bottom: 3px solid var(--accent);
+      }
+
+      h2 {
+        font-size: 1.3rem;
+        font-weight: 700;
+        color: var(--heading);
+        margin: 3rem 0 0.75rem;
+        padding-bottom: 0.4rem;
+        border-bottom: 1px solid var(--border);
+      }
+
+      h3 {
+        font-size: 1.05rem;
+        font-weight: 700;
+        color: var(--accent);
+        margin: 2.5rem 0 0.5rem;
+        padding: 0.4rem 0.75rem;
+        border-left: 3px solid var(--accent);
+        background: linear-gradient(
+          135deg,
+          var(--accent-soft),
+          transparent 80%
+        );
+        border-radius: 0 3px 3px 0;
+      }
+
+      h4 {
+        font-size: 0.92rem;
+        font-weight: 700;
+        color: var(--muted);
+        margin: 2rem 0 0.5rem;
+        padding-bottom: 0.2rem;
+        border-bottom: 1px dashed var(--border);
+      }
+
+      p {
+        margin: 0.8rem 0;
+      }
+
+      a {
+        color: var(--accent);
+        text-decoration-thickness: 1px;
+        text-underline-offset: 2px;
+        transition: text-decoration-thickness 0.15s;
+      }
+
+      a:hover {
+        text-decoration-thickness: 2px;
+      }
+
+      strong {
+        color: var(--heading);
+        font-weight: 700;
+      }
+
+      ol,
+      ul {
+        padding-left: 1.75rem;
+      }
+
+      li + li {
+        margin-top: 0.3rem;
+      }
+
+      code {
+        font-family: "JetBrains Mono", "Cascadia Code", Menlo, Consolas,
+          monospace;
+        font-size: 0.88em;
+        background: var(--code-bg);
+        padding: 0.15em 0.4em;
+        border-radius: 3px;
+        border: 1px solid rgba(0, 0, 0, 0.06);
+      }
+
+      pre {
+        background: var(--code-bg);
+        border: 1px solid var(--border);
+        border-radius: 5px;
+        padding: 1rem 1.25rem;
+        overflow-x: auto;
+        line-height: 1.55;
+      }
+
+      pre code {
+        background: none;
+        padding: 0;
+        border: none;
+        font-size: 0.85em;
+      }
+
+      .heading-anchor {
+        opacity: 0;
+        margin-left: 0.3em;
+        font-weight: 400;
+        text-decoration: none;
+        transition: opacity 0.15s;
+      }
+
+      h1:hover .heading-anchor,
+      h2:hover .heading-anchor,
+      h3:hover .heading-anchor,
+      h4:hover .heading-anchor,
+      .heading-anchor:focus {
+        opacity: 0.4;
+      }
+
+      .heading-anchor:hover {
+        opacity: 1;
+      }
+
+      .page-nav {
+        margin-bottom: 2.5rem;
+        display: flex;
+        gap: 0.5rem;
+        flex-wrap: wrap;
+      }
+
+      .page-nav a {
+        font-family: system-ui, -apple-system, "Segoe UI", Helvetica, Arial,
+          sans-serif;
+        font-size: 0.85rem;
+        font-weight: 600;
+        text-decoration: none;
+        color: var(--muted);
+        padding: 0.3rem 0.75rem;
+        border: 1px solid var(--border);
+        border-radius: 999px;
+        transition: color 0.15s, border-color 0.15s, background 0.15s;
+      }
+
+      .page-nav a:hover {
+        color: var(--accent);
+        border-color: var(--accent);
+      }
+
+      .page-nav a.active {
+        color: var(--bg);
+        background: var(--accent);
+        border-color: var(--accent);
+      }
+    </style>
+  </head>
+  <body>
+    <nav class="page-nav">
+      <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>{{ .Site.Title }}</a>
+      {{ range .Site.RegularPages }}
+      <a href="{{ .RelPermalink }}"{{ if eq $.RelPermalink .RelPermalink }} class="active"{{ end }}>{{ or .Title .File.BaseFileName }}</a>
+      {{ end }}
-      <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>{{ .Site.Title }}</a>
-      {{ range .Site.RegularPages }}
-      <a href="{{ .RelPermalink }}"{{ if eq $.RelPermalink .RelPermalink }} class="active"{{ end }}>{{ or .Title .File.BaseFileName }}</a>
-      {{ end }}
+      <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>{{ or .Site.Home.LinkTitle .Site.Title }}</a>
+      {{ range .Site.RegularPages }}
+      <a href="{{ .RelPermalink }}"{{ if eq $.RelPermalink .RelPermalink }} class="active"{{ end }}>{{ or .LinkTitle .Title .File.BaseFileName }}</a>
+      {{ end }}
-      <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>{{ .Site.Title }}</a>
-      {{ range .Site.RegularPages }}
-      <a href="{{ .RelPermalink }}"{{ if eq $.RelPermalink .RelPermalink }} class="active"{{ end }}>{{ or .Title .File.BaseFileName }}</a>
-      {{ end }}
+      <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>{{ or .Site.Home.LinkTitle .Site.Title }}</a>
+      {{ range .Site.RegularPages }}
+      <a href="{{ .RelPermalink }}"{{ if eq $.RelPermalink .RelPermalink }} class="active"{{ end }}>{{ or .LinkTitle .Title .File.BaseFileName }}</a>
+      {{ end }}
+    </nav>
+    <main>
+      {{ .Content }}
+    </main>
+  </body>
+</html>