#How It Works

The library splits rendering into stages that can be deployed separately. Understanding the pipeline and the two snapshots makes it obvious when to use the root entry and when to parse on the server.

#Pipeline

source
  │
  ├─ (optional) /expand ─▶ expanded source
  │
  ▼
/parse ─▶ WikitextDocument (parse snapshot)
  │
  ▼
/hast prepare ─▶ WikitextRenderDocument (render snapshot)
  │
  ▼
/view ─▶ React

The result of /expand is already a parse document. Do not parse it again; pass it to prepareWikitext.

#Two snapshots

#Parse snapshot WikitextDocument

interface WikitextDocument {
  readonly source: string;
  readonly ast: WikitextRoot;
  readonly syntax?: WikitextSyntaxRoot;
  readonly meta: WikitextDocumentMeta;
  readonly diagnostics: readonly WikitextDiagnostic[];
}

• ast is the normalized semantic tree; preparation never mutates it.
• syntax exists only with retainSyntax: true, for source positions and the playground.
• The same source with a different site config or pageName can produce a different AST.

#Render snapshot WikitextRenderDocument

interface WikitextRenderDocument {
  readonly source: string;
  readonly ast: WikitextRoot; // working tree after plugins
  readonly hast: import("hast").Root; // final sanitized HAST
  readonly headings: readonly WikitextHeadingInfo[];
  readonly meta: WikitextRenderMeta;
  readonly diagnostics: readonly WikitextDiagnostic[];
}

• hast already contains the TOC, reference section, and category footer.
• ast is the working tree after plugins; node ids have been reassigned.
• meta records the effective policy, labels, heading strategy, and authorized images.
• WikitextView accepts only a render snapshot, never source text.

Queries must use the right snapshot: do not look up ids from a render snapshot in the original parse snapshot.

#Why two stages

Parsing is expensive, while preparation options change often. Cache the parse snapshot and prepare it again with different resolvers, images, labels, or plugins instead of reparsing. Server preparation and client rendering use the same snapshot: the client loads no parser and reruns no plugins.

Preparation works on a cloned tree, so the parse snapshot stays read-only. Snapshots are plain data: they can be cached, sent through a worker, or transferred over the network, and restore functions revalidate structure and budgets.

#Semantic normalization

The upstream parser returns a syntax tree. The library normalizes structure during the semantic stage; the React layer never scans source text.

Structures that cannot be represented safely or correctly degrade to a source card and a diagnostic; the library does not guess. Templates, parser functions, arguments, and files render explicit placeholders, so "not evaluated" is never mistaken for "evaluated".

Source HTML is handled by category: allowlisted tags render, forbidden tags are dropped with a readable hint, and unknown tags degrade. Links and images are validated again during finalization: protocol, target, rel, and image authorization.

The goal is explainable, auditable output, not maximal Wikipedia fidelity.

#Entry boundaries

See Entry points for the full export list.

#Glossary

#Next steps

• Basic usage: source component and explicit pipeline.
• Server rendering: snapshot serialization, Next.js, and hydration.
• Preparation /hast: plugins, resolvers, policy, and restore.