Skip to content
Network/Access THE DEFINITIVE GUIDE

ADR-0016: Rich artifacts in the Book — markdown spine, served HTML, Mermaid diagrams

ADR-0016: Rich artifacts in the Book — markdown spine, served HTML, Mermaid diagrams

Status

Accepted

Date

2026-06-25

Context

The Book (apps/book) is an Astro Starlight site that sources canon Markdown from the repo-root docs/ directory via a glob content loader, and provides full-text search through Pagefind, which indexes only the Starlight-rendered doc pages (those carrying data-pagefind-body) — not files served from public/.

We increasingly produce rich visual artifacts that are not plain prose: self-contained Vinxi-branded HTML explainers (e.g. the SmartProjects one-pager, the fiber and oil-gas courses) and diagrams (architecture, flow, state machines). These already exist in two forms — the courses are served as standalone HTML from apps/book/public/courses/… — but they are not discoverable through search or the sidebar, and there was no agreed convention for diagrams.

We need a durable answer to: how do rich HTML and diagrams live in the Book while staying highly discoverable and searchable, alongside the canon Markdown? The constraints that shape it: Pagefind indexes doc pages only; the build runs in CI/Vercel and must not depend on a headless browser; everything visual must follow the Vinxi design system (see the vinxi-brand skill).

Decision

Markdown/MDX is the searchable spine; rich artifacts hang off it.

  1. Every rich artifact has a Markdown (or MDX) doc page in the appropriate room. That page is the canonical, navigable, Pagefind-indexed unit (and flows into the generated llms.txt). It carries a distilled, searchable summary even when the richness lives elsewhere.
  2. Standalone rich HTML (Vinxi explainers, courses) lives in apps/book/public/<category>/, served at /<category>/…, and is linked — and optionally <iframe>-embedded — from its doc page. Because Pagefind does not index public/, the paired doc page is the searchable proxy.
  3. Diagrams, in order of preference:
    • Mermaid (```mermaid fences) for flow / architecture / sequence / state diagrams. Rendered client-side via the astro-mermaid integration (no build-time browser dependency), themed to the Vinxi palette. The fence source is text, so diagrams are diffable, LLM-readable, and the source words are indexed by Pagefind.
    • Inline SVG in Markdown for bespoke schematics that Mermaid cannot express.
    • tldraw (or similar canvas tools) used as an authoring tool only: export to SVG, commit the SVG (keeping the .tldr source alongside for editing). No live tldraw canvases in docs.
  4. MDX is enabled (@astrojs/mdx) so doc pages may embed components/iframes inline; plain .md continues to work unchanged. The content-loader globs accept .md and .mdx.
  5. All generated visuals use the Vinxi design system (per the vinxi-brand skill / Patterns).

Alternatives Considered

  • Raw HTML in public/ only, no Markdown proxy. Simplest, but the artifact is invisible to search and the sidebar — exactly the gap we hit with the courses. Rejected: discoverability is the whole point.
  • Build-time Mermaid (rehype-mermaid + mermaid-isomorphic/Playwright). Produces static SVG indexable as markup, but adds a headless-browser dependency that is heavy and fragile in CI/Vercel. Rejected: build safety outweighs the marginal indexing benefit, and the fence source is already searchable.
  • Live tldraw React islands in docs. Interactive, but requires a React renderer, ships a heavy canvas, and is not searchable. Rejected for docs; tldraw remains fine as an authoring tool.
  • Custom Pagefind scope over the public/ HTML. Possible, but the standalone explainers are not structured with Pagefind’s data-pagefind-body regions, so results would be noisy. The Markdown-proxy rule gives a curated, higher-quality search surface instead.

Consequences

  • Easier: rich explainers and diagrams become first-class, discoverable canon — searchable, in the nav, and in llms.txt. Diagrams are diffable text. Brand consistency is enforced. Authors get three clear, ranked diagram options.
  • What we now owe: each rich HTML needs a paired Markdown page (a small, deliberate summary duplication) and a copy/sync step keeping apps/book/public/<category>/ aligned with any canonical source under docs/. Mermaid renders client-side, so a diagram needs JS to draw (its source text is still indexed); this is acceptable for an internal docs site.
  • Sensitive to: if we later require full-text search inside a rich HTML explainer, this ADR should be revisited — either by converting that explainer to MDX (so Starlight renders and indexes it) or by scoping Pagefind over selected public/ pages.