scaffolder | features | documentation | decisions | starlight-over-alternatives

project:     scaffolder
feature:     documentation
doc-type:    DECISION
status:      accepted
version:     0.1
updated:     2026-03-22
depends-on:  scaffolder | features | documentation | DISCOVERY

Context

A human-readable doc site is needed for projects.purlshq.com — a private, browser-accessible view of all project documentation. The source of truth stays on disk and in the private GitHub repo purlshq/projects. The site is a rendered view for the operator.

Requirements identified during discovery:

Hierarchical navigation mirroring the local docs/ folder structure
Auto-generated sidebar — no manual config per new page or project
Private — locked to operator only via Cloudflare Access
Deployed to projects.purlshq.com via Cloudflare Pages
Markdown-native — Joker writes files, site renders automatically on push
Extensible — custom components may be needed as the system grows
One private GitHub repo: purlshq/projects

Options considered

VitePress — Vue-powered static site generator. Clean minimal aesthetic, fast builds, full-text search built in. Sidebar requires manual configuration per section — every new page or project folder must be registered in a config file. No breadcrumbs out of the box. No right-side page nav by default. Good for simple doc sites where structure is stable and manually maintained.

Starlight (Astro) — Documentation framework built on Astro. Auto-generates the sidebar from the folder structure, meaning new pages and projects appear in navigation automatically without config changes. Right-side page nav, breadcrumbs, light/dark toggle, and search all included out of the box. React-adjacent (Astro) ecosystem makes future extension straightforward. Natively supported on Cloudflare Pages.

MkDocs Material — Python-based, extremely low maintenance, also auto-generates nav from folders, beautiful default theme. Loses on extensibility — Python ecosystem limits custom component work if the site ever needs interactive elements or project dashboards.

Docusaurus — React-based, Facebook-maintained, very mature. Heavier than Starlight, more config required, designed for open source product docs with versioning and blog. Overkill for private internal project docs.

Sphinx, Hugo — Not suited to this use case. Sphinx is code/API documentation focused (reStructuredText). Hugo requires manual theme selection and config with no obvious single winner for this structure.

Cloudflare Pages native support confirmed for all options via developers.cloudflare.com/pages/framework-guides/

Decision

Starlight on Cloudflare Pages, deployed to projects.purlshq.com, locked via Cloudflare Access, source in private repo purlshq/projects.

Rationale

The single most important requirement is auto-generated sidebar navigation. The project structure is deep and grows continuously — new projects, new features, new doc types added regularly by Joker. A system requiring manual sidebar config per page creates ongoing maintenance overhead and is a brain-fog failure point for the operator.

Starlight generates the sidebar from the folder structure automatically. Adding veil/features/music-system/SPEC.md to the repo makes it appear in navigation on next deploy. No config file to update. No step to forget.

Breadcrumbs and right-side page nav are critical for deep hierarchies. A SPEC or ARCHITECTURE doc can be long — right-side “on this page” nav means the operator can orient quickly without scrolling blind. VitePress does not provide this by default.

Extensibility breaks the tie against MkDocs Material. The Astro/React ecosystem allows custom components, interactive elements, and future expansion (project status dashboards, cross-project views) without rebuilding. Python-based tooling would constrain that path.

Consequences

Harley builds the Starlight site once as a scaffolder sub-project
purlshq/projects private repo mirrors D:\scaffolder-engine\projects\
Folder structure = nav structure — no additional config required per project
Joker writes markdown files, git push triggers auto-deploy via Cloudflare Pages
Cloudflare Access locks projects.purlshq.com to operator email only (free)
Future option: each project gets its own subdomain (e.g. veil.purlshq.com) as a separate Cloudflare Pages project from the same repo — up to 5 projects per repo supported natively

DECISION — accepted. Do not modify. Produce SPEC separately.