[pandres95]

specsite v0.1: publish a repository's Markdown specs as living Starlight pages and as single-file HTML snapshots, from one pipeline.

What is in it

• Starlight plugin specsite({...}), configured in astro.config with an allowlist of documents (files and globs). It adds a sidebar group, a small stylesheet in Starlight's own variables, and a Mermaid renderer bundled with the site and loaded only on pages that have a diagram.
• Content loader specsiteLoader(docsLoader()) for src/content.config.ts. The pages become ordinary entries of the docs collection: each is rendered by the site's own Markdown processor (renderMarkdown), so heading anchors, asides, Expressive Code, the table of contents, previous/next, edit links and Pagefind all apply unchanged. Nothing is written to src/content/docs and nothing generated is committed.
• split: 'h2': one page per H2 section plus an index page; every heading keeps its GitHub anchor, and links to it from any document go to the page that holds it.
• Identifiers: definitions found by four rules in priority order (bold at the start of a block, first cell of a table row, heading, list item), anchored at the lower-cased ID (REQ-DI-4 → #req-di-4) on the page that holds them; every other mention, in code or running text, links there across pages and documents. Undefined references and same-kind duplicate definitions are reported with file:line; check: 'error' fails the build. Definitions rank first in search for their ID.
• Links: relative links between listed documents become site URLs; links to other repository files go to the repository host (repoUrl, branch).
• Source line and edit link per page, from git at build time.
• CLI specsite html <file.md> -o out.html [--brand] [--accent] [--with file=url] [--check]: the same pipeline into one self-contained page (contents rail, light/dark, inline CSS; Google Fonts is the only external request and is optional). Ported from a pandoc-based md2artifact.py, so there is one implementation.
• Tests and CI: unit tests for identifier detection and linking, link rewriting and the CLI; example/ is an invented project (Tidepool) built by CI with the Swimming on Code theme.
• Repo: README (with a Roadmap: backlinks, tombstones, a needs.json export), MIT licence (replacing the initial commit's dual licence), CONTRIBUTING with DCO sign-off, SECURITY placeholder.

Why a content loader

Starlight renders only its docs collection, and the content layer is the supported way to feed a collection from files outside src/content. A wrapping loader keeps Starlight's own loader for hand-written pages and adds the generated ones beside them, rendered by the site's configured processor. Injecting routes with <StarlightPage> would need no change to content.config.ts, but would bypass the site's Markdown pipeline (Expressive Code, asides, heading links) and Starlight's autogenerated sidebar and pagination.

Tried on a real project

Built against a private spec-driven project's docs site (Astro 7.3.5, Starlight 0.42.4), locally only: SPEC.md split at H2 plus PLAN.md and OVERVIEW.md gave 19 pages, 675 identifiers and 2,164 links; the specsite step took about 0.6 s and the whole site build 8 s.

🤖 Generated with Claude Code