Skip to content
fzymgc-house Cluster Docs

Use isolated website/ subproject with externalDocsLoader for Starlight docs

Date: 2026-06-07 Status: Superseded by hl-bit.30 Decision: hl-6iz Deciders: Sean Brandt

Context

Section titled “Context”

Astro Starlight’s stock docsLoader() hardwires its content base to srcDir/content/<collection> and cannot read content outside the project tree. The MkDocs→Starlight migration must keep serving repo-root docs/ (preserving every CLAUDE.md routing pointer, edit_uri, and the docs-audit cross-check paths) while keeping Node/pnpm tooling out of the root of a primarily Ansible/Terraform/k8s repo.

Decision

Section titled “Decision”

Use an isolated website/ Astro subproject containing all Node tooling, with a thin custom externalDocsLoader that wraps Astro’s glob() loader with an external base (new URL('../docs', config.root)) paired with Starlight’s docsSchema(). Content stays at repo-root docs/.

Rationale

Section titled “Rationale”
  • Symlinking src/content/docs → ../docs is explicitly unsupported by Astro and behaves inconsistently across OS/build environments — hard reject.
  • Astro at the repo root pollutes an infra repo with package.json/node_modules/lockfile.
  • The glob() + docsSchema() external-base pattern is a documented Astro mechanism (grounded via deepwiki/context7), reducing residual risk to a slug/sidebar/edit-link fidelity spike rather than a feasibility gamble.
  • docs/ stays canonical, so every downstream consumer (CLAUDE.md routing, edit links, cross-check scripts) keeps working unchanged.

Alternatives Considered

Section titled “Alternatives Considered”
  • Symlink src/content/docs → ../docs — zero-config, but unsupported by Astro and OS-inconsistent. Rejected.
  • Astro at repo root — docsLoader() works natively with no custom shim, but Node tooling lands at the root of an Ansible/Terraform/k8s repo. Retained only as the fallback if the loader fidelity spike fails.
  • Idiomatic src/content/docs/ move — cleanest for the framework but rewrites every docs/... path across all CLAUDE.md files and tooling; highest blast radius. Rejected.

Consequences

Section titled “Consequences”
  • Positive: Node dependency graph fully isolated under website/; all existing CLAUDE.md doc pointers remain valid; starlight-llms-txt and starlight-links-validator operate normally on the rendered page graph (downstream of the loader).
  • Negative: a loader-fidelity spike gates Phase 3; falling back to repo-root Astro would require revisiting trigger paths and CI config.
  • Neutral: CI build command changes from uvx mkdocs build to pnpm --dir website build; the Cloudflare Pages deploy structure is unchanged (output dir becomes website/dist).

References

Section titled “References”
  • Superseded by: hl-bit.30