Skip to content
→ All work

Case study 35 / 37

DocAtlas

A documentation site engine whose cross-references cannot go stale: live code includes from the real source tree, dead links that fail the build, and BM25 search.

Status
In development
Period
2026
Domain
Web · Tools
Language
TypeScript
Last push
26 OCT 2026
License
MIT
Source of claims
README.md, docs/architecture.md, CHANGELOG.md, src/cli.ts, src/snippets/extractor.ts, test/site/output-links.test.ts, .github/workflows/ci.yml; check/build/search run from a fresh clone 2026-10-25
docatlas-generated documentation site home page, light theme

01/The problem

Documentation accumulates code samples that were right the day they were pasted and links that worked until a page was renamed. Most tooling treats both as proofreading; DocAtlas treats them as build failures.

02/The system

Code fences can include a file, a marked region or a line range, filled from the real source at build time. Every relative link and heading anchor is resolved against the fully parsed page graph, and a dead one fails the build. Search is a compile-time inverted index ranked with Okapi BM25, using the same ranking module in the browser and on the command line.

Build pipeline (docs/architecture.md)6 components
  • parseMarkdown to resolveSnippets
  • resolveSnippets to Page[]
  • Page[] to checkLinks
  • Page[] to buildIndex
  • Page[] to renderPage

03/Implementation

  1. 01A hand-written Markdown parser for documentation prose: headings, lists, blockquotes, fenced code and inline links.
  2. 02Live includes: include="file.ts", a docatlas:start/end marker region (matched regardless of comment syntax) or a line range, injected into required-empty fences.
  3. 03A link and anchor checker that runs once over the whole page graph, so cross-page anchors can be verified, and rewrites links to the .html files actually written.
  4. 04A shared tokenizer and light stemmer, an inverted index built at compile time, and BM25 ranking used by both the in-page search box and docatlas search.
  5. 05build, check, serve and search subcommands over the same pipeline.

04/Engineering

check is build, pointed at a temp directory

Validation happens as a side effect of building, so there is no separate “just validate” path that could drift from what build actually does.

Link checking after every page is parsed

A cross-page anchor needs the other page's heading slugs, so every page is parsed and snippet-resolved before checkLinks runs over the graph.

It builds its own docs

A CI dogfood job builds and checks the project's docs with the binary it just compiled, and a test crawls the built HTML for unresolvable links.

05/Interface

docatlas's own documentation site, built by docatlas, open on the home page.
The Live Includes guide in dark theme, including a code block injected at build time from src/snippets/extractor.ts.
The built-in search box returning BM25-ranked pages, with scores, for the query 'dead link anchor'.

Real screenshots of the running software. Captions state the data shown.

06/Tech stack

  • TypeScript
  • Node.js
  • Okapi BM25
  • Vitest
  • ESLint
  • GitHub Actions

07/Result

Verified outcomes

  • 200 tests with about 97% statement coverage, run by CI on Linux, Windows and macOS (per the README).

Known limitations

  • The parser targets documentation prose, not the full CommonMark grammar.
  • Not published to npm; it is built from a clone.

08/Links

GitHub repository ↗

Related work

Next case study

RepoGraph →