docs: render repo Markdown as a Mintlify site with gated Pages deploy

[oxfern]

Opening this as a proposal rather than a finished call — CONTRIBUTING asks that new features get discussed first, so treat the deploy half as a question and the build half as the useful part regardless of the answer.

What this does

Renders the Markdown already in this repo as a browsable docs site. The Markdown stays the source of truth; docs/site/build.py copies the subset listed in PAGES into a Mintlify tree, adds frontmatter and navigation, and nothing edits the source files.

Right now the docs are repo-only. block.github.io/buzz/ serves terms/privacy/support, and the README doesn't link to it, so reading ARCHITECTURE.md or the NIPs means grepping raw Markdown on GitHub.

What it looks like

Rendered from this repo's Markdown, unmodified:

45 pages: Architecture, Self-Hosting, Agents, all 15 NIPs, Vision, Project.

Why the deploy is opt-in

Two things make an unconditional deploy destructive, so publishing is gated behind a DOCS_PAGES_DOMAIN repository variable.

It would take the legal site offline. Pages currently serves index/privacy/support/terms from the pages branch as a legacy build. Using actions/deploy-pages switches the source to GitHub Actions, and those pages stop resolving.

Mintlify can't be served from block.github.io/buzz/. The static export hardcodes root-absolute asset paths with no basePath option. I tried rewriting the paths to fit a subpath; the HTML still serves with a 200 and a correct <title>, but React fails to hydrate and every page renders Application error: a client-side exception has occurred. Worth knowing that HTTP-level checks pass while the site is entirely broken — only a real browser render catches it.

So until a maintainer sets DOCS_PAGES_DOMAIN to a hostname pointed at Pages, every run builds, validates and link-checks without publishing. Merging this changes nothing user-visible.

Workflow

Triggers on push to main and on PRs touching *.md, docs/**, the three crate READMEs and deploy/compose/README.md. It builds, runs mint validate, runs mint broken-links, and uploads the site as an artifact. The deploy job is skipped unless the variable is set.

mint validate is load-bearing: a page routed to a name Mintlify reserves is dropped from the build and reported as "file does not exist" with no parse error. changelog and contributing are both reserved, which is why CHANGELOG.md and CONTRIBUTING.md route to project/release-notes and project/contributing-guide.

Adding a page

Add it to PAGES in build.py. Group placement follows the route prefix, so a new architecture/… route joins that group with no other change.

Open questions

• Is a docs site something you want in-tree at all, or would you rather use Mintlify's hosted product and connect the repo there?
• If yes, is there a hostname available? docs.buzz.xyz would work, and it leaves block.github.io/buzz/ serving the legal pages untouched.
• mint export runs unauthenticated in the CLI, but Mintlify documents static export as an Enterprise API feature. Worth confirming it holds in CI before enabling the deploy.

Verification

build.py was run against this branch: 45 pages, mint validate and mint broken-links both clean. The screenshots are that build served from a domain root, rendered in a browser rather than checked by status code.