docs-site/docs-snippets

Extracts the code snippets of a package’s documentation guides and type-checks them against its sources.

A guide’s snippet is code a reader copies, so a renamed member or a stale import path in it is a bug that ships to the site with every check green. Every fenced ts, typescript, js or javascript block in docs/src/content/docs is compiled as its own module, with the project’s tsconfig.json, so an import of the package’s own name resolves wherever that configuration sends it (its paths, or the compilerOptions passed here) and a wrong name fails. A ts / typescript block is compiled as TypeScript; a js / javascript block, often a devtools-console recipe, is compiled as JavaScript with checkJs, so a wrong member of a typed object still fails while an untyped lookup does not. The generated API reference (docs/src/content/docs/api) is skipped: it is rendered from the TSDoc.

Three things shape what a snippet is compiled with, each but the first written in the guide as an HTML comment, invisible on the site, on the lines right above the fence:

• The names every guide may use without declaring them are the package’s prelude, compiled as a module of its own (a declare global block, with the imports it needs). - <!-- snippet-check: context <TypeScript> --> prepends declarations to that one snippet, for the names its prose has already introduced (declare const linkEl: HTMLAnchorElement;). Several such lines add up. - <!-- snippet-check: skip <reason> --> exempts a snippet that is deliberately not compilable, such as pseudo-code. The reason is required, so a skip is a decision somebody wrote down, never a silent hole.

Interfaces

Interface	Description
DocsSnippet	One fenced code block of a guide.
DocsSnippetProblem	A problem found in a guide’s snippet.
FindDocsSnippetProblemsParams	Parameters for findDocsSnippetProblems.

Functions

Function	Description
assertDocsSnippetsCompile	Type-checks every snippet of the guides and throws when one fails, for a docs:check-snippets script.
extractDocsSnippets	Extracts the fenced code blocks of the checked languages from a markdown document. A fence inside a blockquote or a list item is recognized too: its prefix (> , indentation) is stripped from every line of its code.
findDocsSnippetProblems	Type-checks every snippet of the guides.
formatDocsSnippetProblems	Formats problems one per line, as path:line - message.

Types

Type	Description
AssertDocsSnippetsCompileParams	Parameters for assertDocsSnippetsCompile: the same as findDocsSnippetProblems takes.