From a2b27ebca619ae8210391c79bae61ab6afcba1bf Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 15 May 2026 22:46:46 +0000 Subject: [PATCH 1/2] 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 `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) --- .gitignore | 4 + docs/hugo.toml | 14 ++ .../_default/_markup/render-heading.html | 4 + docs/layouts/_default/default.html | 207 ++++++++++++++++++ mise.lock | 72 +++++- mise.toml | 9 + 6 files changed, 308 insertions(+), 2 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 26fa4960..7a4f8808 100644 --- a/.gitignore +++ b/.gitignore @@ -130,3 +130,7 @@ Backup*/ UpgradeLog*.XML .doxygen.conf + +# Hugo docs build output +docs/.hugo_build.lock +docs/public/ diff --git a/docs/hugo.toml b/docs/hugo.toml new file mode 100644 index 00000000..4043322a --- /dev/null +++ b/docs/hugo.toml @@ -0,0 +1,14 @@ +baseURL = "https://maxmind.github.io/minfraud-api-dotnet/" +title = "MaxMind minFraud .NET API" +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..849a0dfe --- /dev/null +++ b/docs/layouts/_default/default.html @@ -0,0 +1,207 @@ + + + + + + {{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ or .Title .File.BaseFileName }} | {{ .Site.Title }}{{ end }} + + + + +
+ {{ .Content }} +
+ + diff --git a/mise.lock b/mise.lock index b3c22404..7672af76 100644 --- a/mise.lock +++ b/mise.lock @@ -5,11 +5,11 @@ version = "10.0.201" backend = "core:dotnet" [[tools.dotnet]] -version = "9.0.312" +version = "8.0.419" backend = "core:dotnet" [[tools.dotnet]] -version = "8.0.419" +version = "9.0.312" backend = "core:dotnet" [[tools."github:houseabsolute/precious"]] @@ -51,6 +51,38 @@ checksum = "sha256:9d683d1730e302c646ccb90a23d313e7a548c8b23b5abf7d24e19ff6befe7 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.hugo."platforms.linux-arm64"] +checksum = "sha256:382371ec3208236fb854ced51781f859b6c27a7d066b8fe90594eba14ba76d00" +url = "https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_0.161.1_linux-arm64.tar.gz" + +[tools.hugo."platforms.linux-arm64-musl"] +checksum = "sha256:382371ec3208236fb854ced51781f859b6c27a7d066b8fe90594eba14ba76d00" +url = "https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_0.161.1_linux-arm64.tar.gz" + +[tools.hugo."platforms.linux-x64"] +checksum = "sha256:fae28bf7909c1a42d1365b89d2e9e3d4194fbe5968ae0dd5504f562381018a1d" +url = "https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_0.161.1_linux-amd64.tar.gz" + +[tools.hugo."platforms.linux-x64-musl"] +checksum = "sha256:fae28bf7909c1a42d1365b89d2e9e3d4194fbe5968ae0dd5504f562381018a1d" +url = "https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_0.161.1_linux-amd64.tar.gz" + +[tools.hugo."platforms.macos-arm64"] +checksum = "sha256:b12e1cbebacf61f9cf67e0046c835142e70c829da7c16b05c1ec64a68885ee80" +url = "https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_0.161.1_darwin-universal.pkg" + +[tools.hugo."platforms.macos-x64"] +checksum = "sha256:b12e1cbebacf61f9cf67e0046c835142e70c829da7c16b05c1ec64a68885ee80" +url = "https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_0.161.1_darwin-universal.pkg" + +[tools.hugo."platforms.windows-x64"] +checksum = "sha256:7f8d030b37600c60bf2a782611257e6a768934fbe7724c1f3a1a501e6724cf0d" +url = "https://github.com/gohugoio/hugo/releases/download/v0.161.1/hugo_0.161.1_windows-amd64.zip" + [[tools.node]] version = "25.8.1" backend = "core:node" @@ -83,6 +115,42 @@ url = "https://nodejs.org/dist/v25.8.1/node-v25.8.1-darwin-x64.tar.gz" checksum = "sha256:09a5a0dbb2f4cefa800880012810e2dfaac0016a62e75f064c4ab7f3606b2d78" url = "https://nodejs.org/dist/v25.8.1/node-v25.8.1-win-x64.zip" +[[tools.node]] +version = "26.1.0" +backend = "core:node" + +[tools.node."platforms.linux-arm64"] +checksum = "sha256:fcb4c339eef70c909cae72091008a6497278e2d0fcd221c0653068cf4ea4f0c7" +url = "https://nodejs.org/dist/v26.1.0/node-v26.1.0-linux-arm64.tar.gz" + +[tools.node."platforms.linux-arm64-musl"] +checksum = "sha256:fcb4c339eef70c909cae72091008a6497278e2d0fcd221c0653068cf4ea4f0c7" +url = "https://nodejs.org/dist/v26.1.0/node-v26.1.0-linux-arm64.tar.gz" + +[tools.node."platforms.linux-x64"] +checksum = "sha256:62d555c329e05e3625109f2e3a8b5195b368d5ef38266292469d32f63cd98ffd" +url = "https://nodejs.org/dist/v26.1.0/node-v26.1.0-linux-x64.tar.gz" + +[tools.node."platforms.linux-x64-musl"] +checksum = "sha256:62d555c329e05e3625109f2e3a8b5195b368d5ef38266292469d32f63cd98ffd" +url = "https://nodejs.org/dist/v26.1.0/node-v26.1.0-linux-x64.tar.gz" + +[tools.node."platforms.macos-arm64"] +checksum = "sha256:91063f665c2f5d6e69e4f8fcb66d3d476bc2785ace82267274bf4da789985ceb" +url = "https://nodejs.org/dist/v26.1.0/node-v26.1.0-darwin-arm64.tar.gz" + +[tools.node."platforms.macos-x64"] +checksum = "sha256:33519b28a352de668ab0a2a64366db032a45cb629d5353f86e4576e2780f4fcf" +url = "https://nodejs.org/dist/v26.1.0/node-v26.1.0-darwin-x64.tar.gz" + +[tools.node."platforms.windows-x64"] +checksum = "sha256:089a02c4c687451c9f0b7f1bfd252dae85a7ba27df0295a14096bdcc956fdc92" +url = "https://nodejs.org/dist/v26.1.0/node-v26.1.0-win-x64.zip" + [[tools."npm:prettier"]] version = "3.8.1" backend = "npm:prettier" + +[[tools."npm:prettier"]] +version = "3.8.3" +backend = "npm:prettier" diff --git a/mise.toml b/mise.toml index 234f6553..3563299e 100644 --- a/mise.toml +++ b/mise.toml @@ -8,10 +8,19 @@ disable_backends = [ [tools] dotnet = ["latest", "9", "8"] +hugo = "latest" "github:houseabsolute/precious" = "latest" node = "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" + [hooks] enter = "mise install --quiet --locked" From 6bea096388f5ad79303a63556508eee6484e314b Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 15 May 2026 22:46:46 +0000 Subject: [PATCH 2/2] 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. 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/` Doxygen subtree exactly as it lives on gh-pages today. 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) --- .github/workflows/pages.yml | 40 +++++++++++++++++++++++++++++++++++++ 1 file changed, 40 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..047fb0ae --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,40 @@ +name: Deploy to GitHub Pages + +on: + push: + branches: ["main"] + workflow_dispatch: + +permissions: {} + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: true + + - name: Setup mise + uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8 # v3.6.1 + with: + cache: true + + - name: Build docs + run: mise run build-docs + + - name: Push rendered site to gh-pages + uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/public + publish_branch: gh-pages + keep_files: true + user_name: "github-actions[bot]" + user_email: "41898282+github-actions[bot]@users.noreply.github.com"