A Starlight docs toolkit that verifies API references against source AST and keeps multilingual docs in parity.
Combines a Rust pipeline powered by tree-sitter with TypeScript plugins for OG images, glossaries, related pages, semantic doc graphs, and Diátaxis linting. Built for maintainers of Starlight sites who need fast, deterministic docs QA without hardcoded strings.
Quickstart • Features • How it works • Usage • Status
Requires Node.js 20+ and pnpm.
pnpm add @elcoosp/docs-toolkit// astro.config.mjs
import { defineDocsConfig } from '@elcoosp/docs-toolkit/config';
export default await defineDocsConfig({
site: 'https://example.com',
domain: 'example.com',
title: 'My Docs',
description: 'Documentation for my project',
plugins: {
smartTocProgress: true,
termGlossary: true,
i18nParity: true,
relatedPages: true,
diataxisLint: true,
linkPreview: true,
readingContext: true,
apiDrift: { strict: false },
snippetDrift: { strict: false },
docGraph: { strict: false, warnOrphans: true },
},
});pnpm buildRust pipeline completed in 12 ms — doc-graph (42 nodes, 142 edges, 0 orphans) · api-drift (86% cov, 0 phantom) · snippet-drift (52 blocks, 0 issues)
- AST-verified API & snippet drift:
api-driftandsnippet-driftparse Rust and TypeScript with tree-sitter, flagging phantom symbols, syntax errors, and stale versions in/reference/pages and code blocks. - Semantic doc graph & PageRank:
doc-graphcomputes the directed link graph per locale, ranks hub pages with PageRank, detects orphan pages, writesdist/graph.json, and surfaces connected pages inside the⌘Kpalette. - Multilingual parity:
i18n-parityensures every key ini18n/en.jsonhas a matching entry in every locale, using the conventional Starlight translation flow. - Diátaxis-aware linting:
diataxis-lintchecks that pages fit one of the four documentation types and warns when a tutorial becomes reference or vice versa. - Fast native pipeline: the Rust
docs-pipeline-rscrate runs AST extraction, link graph analysis, and API indexing in parallel with rayon, adding milliseconds to a build. - OG images and badges: auto-derived accent colours, per-page PNG generation, and section badges from a single
defineDocsConfigcall. - Discovery plugins:
⌘Kcommand palette, related pages, term glossary, smart TOC progress, link preview, and reading context. - No hardcoded strings: every user-facing message flows through
injectTranslationsand the standardi18n/*.jsonfiles.
defineDocsConfig wires Starlight plugins into the Astro build. When the native pipeline is enabled, the Rust binary builds a public-API index from your repository using tree-sitter, computes the directed documentation graph, and audits /reference/ routes and code snippets in parallel.
flowchart LR
A[Astro build] --> B[Starlight plugins]
B --> C[Rust docs-pipeline-rs]
C --> D[tree-sitter AST index]
C --> G[Directed doc graph]
D --> E[api-drift & snippet-drift]
G --> K[dist/graph.json & ⌘K palette]
B --> F[i18n parity & Diátaxis lint]
E --> H[Build warnings / errors]
The index covers pub fn, pub struct, pub enum, pub trait, enum variants, trait methods, macros, pub use re-exports, and TypeScript export declarations. The comparison respects page-level skip lists (language, syntax, grammar, changelog, etc.) and heading-level symbol extraction, so prose titles like “Construction” do not become phantom references.
// astro.config.mjs
import { defineDocsConfig } from '@elcoosp/docs-toolkit/config';
export default await defineDocsConfig({
site: 'https://example.com',
domain: 'example.com',
title: 'My Docs',
description: 'Documentation for my project',
plugins: {
apiDrift: { strict: true, writeReport: true },
snippetDrift: { strict: true, writeReport: true },
docGraph: { strict: false, warnOrphans: true },
i18nParity: { defaultLocale: 'en' },
diataxisLint: { warnOnly: false },
},
});import {
starlightSmartTocProgress,
starlightTermGlossary,
starlightI18nParity,
starlightRelatedPages,
starlightDiataxisLint,
} from '@elcoosp/docs-toolkit';
export default {
plugins: [
starlightSmartTocProgress(),
starlightTermGlossary({
entries: [{ term: 'AST', definition: 'Abstract syntax tree' }],
}),
starlightI18nParity(),
starlightRelatedPages(),
starlightDiataxisLint(),
],
};{
"sourceSymbols": 1232,
"matchedSymbols": 74,
"coveragePct": 6,
"phantoms": [],
"warnings": [],
"errors": []
}Reports are written to dist/api-drift.json, dist/snippet-drift.json, and dist/graph.json during postbuild. Set strict: true to turn phantom references, snippet errors, or orphan pages into build errors.
Note
Stable at v1.6.13. The Rust pipeline ships prebuilt binaries for macOS, Linux, and Windows through assets/bin; building from source requires a Rust toolchain. TypeScript plugins target Starlight on Astro 5+. The test suite covers unit, browser, and real-site e2e projects through Vitest.