ci: build, review and deploy the documentation site

[soimy]

Phase D of #81, stacked on the content migration. Review order: #82 → content migration → this. CI runs here once the stack is on master; the branch is rebased at each step.

The workflow

.github/workflows/docs.yml builds on every change that can affect the site (docs/**, src/**, the manifests, the workflow itself), runs npm run typecheck before generating the API reference, uploads docs/.vitepress/dist as a Pages artifact, and deploys that same artifact to GitHub Pages from master — one build job, Node 24, npm ci --include=dev. The deploy job is gated on a push to master, so a pull request stops after the upload: it gets a downloadable build attached to the run, not a published site and not a preview URL.

One maintainer step is required before the first deployment: switch Settings → Pages → Build and deployment to GitHub Actions. Until that happens npm run doc:publish still pushes the built site to the gh-pages branch the old way, and docs/contributor/documentation.md says the two paths must not be used together.

Legacy URLs keep working

The old site served TypeDoc's HTML from the Pages root, so classes/*.html, interfaces/*.html, enums/PACKING_LOGIC.html, modules.html and hierarchy.html were published addresses. The build now writes a redirect page at each of them, pointing at the page that replaced it, and fails when a target is missing from the build rather than shipping a redirect into a 404 (measured: pointing the Bin redirect at a page that does not exist fails the build and names it).

Legacy anchors that used underscores are rewritten in the browser (#max_area → #max-area). Anchors that belonged to private members cannot be preserved — excludePrivate: true is what keeps implementation members out of the site — and are documented as landing on the page itself.

docs/site.json holds the base path for both the VitePress config and the redirect builder, so the published prefix cannot drift between them.

Verification

Served the built tree locally and fetched every route: the home page, /api/, the user and contributor sections, releases, and all five legacy class/interface/enum paths return 200, with assets referenced through /maxrects-packer/. lint, format:check, typecheck, verify:docs, docs:build, cover (100%) and verify:package all green.

The build ends with an output check

srcExclude is a config option, and a config option is not a check: scripts/verify-docs-output.mjs now inspects what was actually built and asserts both directions — no page tree for spec/ or plans/ (which is also what keeps them out of the search index, since VitePress only indexes pages it built), a built page for every handwritten page, and a search index that carries site text rather than nothing.

Measured both ways: dropping srcExclude fails naming dist/spec and dist/plans; widening it to user/** fails earlier, in VitePress's own dead-link check. The check's first version scanned built pages for the records' file names and failed on docs/contributor/documentation.html, which legitimately links to them — the page tree is the signal, not the names.

The workflow's action inputs were checked against the actions' own action.yml (upload-pages-artifact takes path, setup-node takes node-version/cache, deploy-pages publishes page_url), since none of this can be exercised locally.

Two more checks the build now ends with

• Anchors, not just pages (build: resolve every internal link, anchors included): VitePress fails on a dead page link but says nothing about a missing #anchor, and TypeDoc's own cross-references are full of them. Every relative and root-absolute link in the published markdown is resolved against the built HTML — 188 today — and a renamed section fails the build naming the file, the link and the missing id.
• Reachability (build: fail when a page is built but nothing links to it + build: report the nav coverage when it passes): the check verified each page was built, which is only half of reachable. The config's link: entries are now checked both ways, so a new page that nothing links to fails instead of shipping invisibly outside search. Deleting the Repacking sidebar entry reproduces it.

Clean-checkout verification

Every gate above was also run from a fresh git clone of the chain head into an empty directory — no node_modules, no dist/, no docs/api/, no ignored files — because the worktree the checks were written in is full of build products:

npm ci --include=dev → lint · format:check · typecheck · verify:docs · docs:build · test (126 passed, 2 skipped) · cover (100% on all four metrics) · verify:package, all exit 0; npm pack --dry-run = 28 files / 66,871 B.

The built tree was then served at the real base path, /maxrects-packer/, and all 16 routes returned 200: home, both guide sections, releases, the API root and two generated pages, the five legacy paths (classes/, interfaces/, enums/, modules.html, hierarchy.html), a referenced asset, and 404.html. The classes/MaxRectsPacker.html redirect carries url=/maxrects-packer/api/classes/MaxRectsPacker.html, so the base survives the redirect.

Hashes of this stack's commits are deliberately not quoted: they move on every rebase, so commits are named by subject instead.

Trigger list audited against what the build reads

typedoc.json names tsconfig: "tsconfig.json", so a compiler option there can change the generated API pages — and neither paths list mentioned it. A PR touching only the tsconfig would therefore have left the deployed site describing the previous options until something else triggered a rebuild. Both lists carry it now (12 filters each, checked by parsing the workflow), and the trigger sentence in docs/contributor/documentation.md names the inputs instead of saying "the TypeDoc and package manifests". The rest of the build's inputs were checked the same way and are covered: docs/**, src/**, scripts/**, the two package manifests, the root markdown files and the workflow itself; the site references nothing under assets/, so that directory is deliberately absent.

Review round

The deployment sentence promised a preview: upload-pages-artifact uploads a Pages artifact, it does not publish one, and deploy-pages runs only on master. A pull request therefore gets a downloadable artifact and no URL at all. docs/contributor/documentation.md and the workflow's header comment now say exactly that, and this description was corrected with them.

Consistency pass on the audit numbers

The legacy-anchor section and the spike report it links to disagreed — 105/170 here against a Phase A column adding up to 129/170 there. Nothing reproduces 129 from the published site (exact id 102, after the underscore rewrite 105, on any new page 106, substring of a new id 149, unique names 40 of 98), so the report marks its counts superseded, states the re-measured 105/170 with the three buckets, and this page's pointer says so.

[soimy]

Stack #86 review of current head 70bba8e05ef2049140d4e9786f6e047e8d262c2d.

The Documentation workflow itself is green on this PR: the Node 24 build, Pages configuration, and artifact upload all succeed, while the deploy job is correctly skipped for pull requests. I found one wording/expectation issue below; the workflow implementation otherwise looks sound.

[soimy]

Auditing the other contributor pages against the repository turned up one stale description this PR should own: docs/contributor/development.md's script table still described npm run docs:build as two steps ("Generates docs/api/ and builds the site into docs/.vitepress/dist/"), while docs/contributor/documentation.md in this same PR lists all four. The row now names the redirects and the output check (commit: docs: describe the whole \docs:build` command where it is listed`).

Everything else in the audit checked out against the source: the backend trigger lists, the deploy gate (github.event_name == 'push' && github.ref == 'refs/heads/master'), the Node 24 build job, npm ci --include=dev and the type check before docs:build.

[soimy]

The legacy-URL section said only private-member anchors are lost. That was never measured against the real thing, so I crawled the published 2.7.4 site (https://soimy.github.io/maxrects-packer/, still live) and counted:

• all 11 published HTML pages answer 200, and the internal links they carry are exactly the 10 pages the redirect builder writes plus the root;
• of the 170 member anchors on those 11 pages, 105 resolve on the page that replaced them after the underscore rewrite (#max_area → #max-area);
• the other 65 land on the page itself, and they split three ways: 22 private members (#_dirty, #findnode, #sort — the old theme published them, excludePrivate: true does not), 28 old-theme signature anchors with no heading on the new pages (#dirtydirty, #constructorbint, #widthwidth-1, #collide-2), and 15 sections of the two legacy index pages (modules.html#maxrectspacker, hierarchy.html#Bin), which redirect to api/index.html — that page lists classes, interfaces and enumerations but has no per-entry anchor.

The section now states that split instead of the private-members-only version (commit: docs: record which legacy deep links survive the move). No redirect was added for the last group: the anchors that would have to replace them are TypeDoc's generated slugs for the same entries, and pinning redirects to those would trade a documented landing spot for a brittle one.

[soimy]

Re-review of current head 17ddbf7cfb996b0a29043bdfe133cd37dedc4513.

The previous PR-preview wording issue remains correctly fixed, and both the Node.js CI matrix and Documentation workflow are green.

I found one remaining documentation-consistency issue in the new legacy-link audit:

[soimy]

Rebased on the current #83 head and out of draft. Gates on this head (6500382): Node 20/22/24 matrix green, Build documentation green, Deploy to GitHub Pages correctly skipped on a PR.

Merge order is #83 → #84 → #85: this layer's base is docs/content-migration, so after #83 lands the base needs retargeting to master (the tree is the same; the rebase is mechanical).

[greptile-apps]

Confidence Score: 5/5

[High risk] Adds documentation build and deployment workflow.

No blocking issues were identified; the reviewed changes appear safe to merge.

What we checked:

• VitePress 1.6.4 built the mutated sidebar without error, but the rendered link pointed to a non-existent destination (HTTP 404).
• An output check detected the missing destination during the built-HTML absolute-URL scan, causing npm run docs:build to exit with code 1.
• Evidence shows the valid sidebar link loads the Class page, while the mutated link returns a 404, as demonstrated by the captured images and videos.
• The overall contract validation concludes that the docs build would fail due to the broken absolute URL, confirming the PoW outcome.

Summary

Adds a documentation workflow to build, check, and deploy the site, including legacy URL redirects. No issues requiring changes were identified.

_{Reviews (1) · Last reviewed commit: "build: assert the output serves every UR..."}