Skip to content
Tabletop Tracker

WI-004: Build the docs subsite

WI-004: Build the docs subsite

Problem

Collaborators need to read the architecture, decisions, standards, and backlog at a URL, with search and navigation, without a checkout. ADR-0013 specifies Astro Starlight as apps/docs on Cloudflare Pages, single-sourced from the root docs/ directory.

In scope

  • apps/docs with Astro + Starlight.
  • An Astro content-collection loader using glob({ base: '../../docs' }) so root docs/ is the only copy of every authored file.
  • Sidebar grouping: Architecture · Decisions · Standards · Work.
  • Built-in search working across all sections.
  • Any missing title/description frontmatter added to existing docs/ files.

Split out

  • Cloudflare Pages deploy — moved to WI-007 (#21). It needs credentials from WI-H04 (#12), and the build half is fully verifiable offline. Splitting kept the subsite from being blocked on an account signup, rather than dropping the DoD line.

Out of scope

  • Custom theming or branding beyond Starlight defaults.
  • Authentication or access control — the site is public.
  • Editing the substance of any document. Frontmatter fixes only.

Definition of done

  • pnpm --filter docs dev serves the site locally.
  • pnpm --filter docs build succeeds with zero broken internal links.
  • Every file under root docs/ renders, including architecture.md, all 17 ADRs, all 10 standards, and the work backlog.
  • There are no duplicated markdown files and no symlinks — apps/docs contains no copy of any file that exists in root docs/.
  • Editing one line in docs/decisions/ADR-0008-drizzle-query-layer.md changes the built site with no second edit anywhere.
  • Search returns a result for a term that appears only in a standards document.
  • Relative links between docs/ files work both on GitHub and on the built site.

Verification

Terminal window
pnpm --filter docs build     # must report no broken links
pnpm --filter docs dev
# Visit the local URL: check each sidebar section, then search for a
# standards-only term such as "confident false completion".

Single-source check:

Terminal window
# Should return nothing — no duplicated content files under apps/docs
find apps/docs -name '*.md' -not -path '*/node_modules/*'

Then edit an ADR heading, rebuild, and confirm the change appears with no other file touched.

Notes

The glob loader is the crux. A copy step or symlink approach was explicitly rejected in ADR-0013 — symlinks are painful across the WSL boundary, and any copy step means documentation that requires two edits, which is documentation that rots.