mcpx docs: build the site in CI and deploy to GitHub Pages #1941

Relocated from dezren39/darwin-nix#118 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #90

Summary

Build the docs site in CI and publish it to GitHub Pages: pull requests build only, and pushes to main deploy. The build has to produce the mcpx binary first, because the reference pages are generated from it. The real decision is where the built site is published, because dezren39/nix is the whole nix-config monorepo and GitHub allows one Pages site per repository.

Original notes

• documentation
  • make a book using whatever is the most common and simple modern choice
    • github static setup. separately, assign a subdomain

("separately, assign a subdomain" is #119.)

Current state

• dezren39/nix is public and has no Pages site: gh api repos/dezren39/nix/pages returns 404.
• The user site dezren39/dezren39.github.io is published from a branch (build_type: legacy, master /) with custom domain www.drewrypope.com and HTTPS enforced. So a project site from dezren39/nix would appear at https://www.drewrypope.com/nix/ unless it gets its own custom domain (Update github.com/tursodatabase/libsql-client-go digest to 9d5d30a #119).
• github.com/dezren39/mcpx is the Go module path, but that repository does not exist (gh api repos/dezren39/mcpx returns 404).
• CI:
  • .github/workflows/mcpx.yml runs on PRs touching pkgs/mcpx/**, flake.nix, flake.lock or itself, and on pushes to main touching pkgs/mcpx/**.
  • It installs Nix (DeterminateSystems/nix-installer-action), Go, Deno, Bun and Node, runs go test ./..., and repairs vendorHash on bot branches.
  • Its permissions are contents: write, pull-requests: read.
  • The only other workflow is opencode.yml.
• package.nix postInstall already runs the built binary ($out/bin/mcpx man, mcpx completion ...). A docs derivation can do the same with mcpx as a build input.

What the build must do (any approach)

1. Build mcpx, then run it to emit the generated reference pages (🎨 Palette: Improve accessibility of editor search panel #144 / ⚡ Bolt: Optimize cursor color generation and position grouping #145): settings, commands, OpenAPI, tool types. The docs can then never describe a binary other than the one built from the same commit.
2. Run the generator chosen in chore(deps): update rust crate actix-files to v0.6.10 - autoclosed #117, plus the history renderer (⚡ Bolt: Optimize ProseMirror decoration widget rendering #151) and the agent twin (Update module github.com/jackc/pgx/v5 to v5.9.2 [SECURITY] #120).
3. Bake in the base URL. The site root is / with a custom domain and /nix/ without one. Take it as a derivation argument so a local build and a CI build differ only in that value.

Nix or setup-* actions. Recommended: nix build .#mcpx-docs, a flake output that depends on .#mcpx. It is the same build locally and in CI, it is covered by #49's "build every output" job for free, and the generator version is pinned by flake.lock. The alternative is setup-go plus a generator action. That is faster on a cold runner but drifts from the local build, and it duplicates the pinning. Mitigate Nix's cold-start cost with a Nix store cache (cachix, or the Actions cache via nix-community/cache-nix-action), as #49 proposes for all packages.

Triggers and path filters.

• Deploy on push to main touching pkgs/mcpx/**, flake.lock (a generator or nixpkgs bump) or the workflow file.
• On PRs with the same paths: build only, upload the site as an ordinary artifact, and run the docs checks.
• Also run on workflow_dispatch, for redeploys.
• Use a concurrency: { group: pages, cancel-in-progress: false } group so two deploys cannot interleave.

A separate workflow file (mcpx-docs.yml) rather than a job in mcpx.yml. A Pages deploy needs pages: write and id-token: write plus the github-pages environment. mcpx.yml needs contents: write to push hash fixes. Keeping the two apart keeps each job's token minimal.

PR previews. GitHub Pages has no native PR previews. The options, cheapest first:

1. None. Reviewers download the PR's build artifact and open it locally, e.g. with nix run .#mcpx-docs-serve, a tiny static server. Recommended to start with.
2. rossjrw/pr-preview-action or koizuka/pr-preview-action. These only work when Pages is deployed from a branch, so they are incompatible with Approach C below.
3. A separate preview repository (e.g. EndBug/pages-preview) with its own Pages site. It needs a PAT, and the previews live at a different base URL.
4. An external host with previews (Cloudflare Pages, Netlify). That adds a service and an account.

Docs checks (links, generated pages current, agent twin in sync) run in CI; see the testing trackers under #91 (CI pipeline #95, integration/environments #97).

Approaches: where the built site is published

Approach A (least recommended): a gh-pages branch in dezren39/nix, pushed by CI

This is the classic setup, and the one most PR-preview actions assume.

Why not:

• It commits generated HTML into the config monorepo on every docs change, so the branch grows forever and the history fills with bot commits.
• The workflow needs contents: write on this repository in order to push.
• It is GitHub's "legacy" publishing mode.
• The only thing it buys is option 2 of the PR previews above. That is not worth a permanently growing branch in a repository whose clones every machine pulls.

Approach B (middle): push the built site to a separate repository

For example dezren39/mcpx-docs, with its own Pages site and custom domain.

• It keeps generated output out of the monorepo, allows several docs sites (one per package) without the one-site-per-repo limit, and a separate preview repository becomes natural.
• Costs: a PAT or deploy key stored as a secret in dezren39/nix, a second repository to keep alive, and a history of generated commits there instead.
• Do not use dezren39/mcpx for this. That name is the Go module path. If mcpx ever gets its own repository (so that go install github.com/dezren39/mcpx/cmd/mcpx@latest works), that repository must hold the code. If the code moves there, its docs should move with it and Approach C applies in that repository.

Approach C (recommended): the Actions artifact deploy from dezren39/nix, with its own custom domain

• Set the Pages source to "GitHub Actions" (gh api repos/dezren39/nix/pages -X POST -f build_type=workflow).
• The workflow builds .#mcpx-docs, then runs actions/upload-pages-artifact followed by actions/deploy-pages in the github-pages environment.
• No generated file is ever committed anywhere, and no extra repository or secret is needed.
• It is GitHub's current recommended mode. It also means a CNAME file is ignored and not needed: the custom domain is a repository setting (GitHub docs). See Update github.com/tursodatabase/libsql-client-go digest to 9d5d30a #119.
• The github-pages environment's default protection only allows deploys from the default branch, which is what we want.

Limits:

• One site per repository. If other flake packages later want docs, they share this site under subpaths, which is the open question in chore(deps): update rust crate actix-files to v0.6.10 - autoclosed #117.
• No branch-based PR previews (options 1, 3 and 4 still work).

Open questions

1. One site for the whole monorepo with mcpx at the root, or an mcpx-only site? This decides whether a second package's docs would push towards Approach B.
2. Deploy on every main push touching mcpx, or only on release tags once amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158 exists? The install page must not document a channel before it is live, so release-gated deploys (or at least release-gated install instructions) may be needed.
3. Is the Nix cold-start time acceptable for a docs deploy? Measure with gh run view --log on the first runs, and compare with mcpx.yml timings.
4. Should the docs build be required on main together with the mcpx build (build(deps): bump build/buck/preludes/buck2-prelude from d956689 to 3cfc766 #49 proposes making the mcpx check required)?

Ease · Impact · Related

Ease M (workflow + flake output; most of the effort is the flake output that runs mcpx to generate pages) · Impact high (nothing is public without it) · Depends on / related: #117 (generator), #119 (domain), #120, #144, #145, #151, #158, #49

Security/auth deferred; see tracker.