#Template Expansion

The default pipeline does not execute templates. When you need template output, use /expand to expand supported templates and parser functions before parsing. The library makes no network requests; the host's resolveTemplate supplies template source.

#Basic usage

import { expandWikitext } from "react-wikitext/expand";
import { prepareWikitext } from "react-wikitext/hast";
import { WikitextView } from "react-wikitext/view";
import "react-wikitext/styles.css";

const expanded = await expandWikitext(source, {
  pageName: "Example",
  resolveTemplate: async ({ title }) => {
    const response = await fetch(`/api/templates/${encodeURIComponent(title)}`);
    return response.ok ? await response.text() : null;
  },
});

const prepared = prepareWikitext(expanded.document);
const view = <WikitextView document={prepared} lang="en" />;

expandWikitext:

1. Parses the original source into original.
2. Evaluates templates and functions by call structure and records records.
3. Parses the expanded source into document.
4. Returns expansion.status: "complete", "partial", or "fallback".

The expanded document is already parsed. Do not parse it again; pass it directly to prepareWikitext.

#Resolver requirements

type WikitextTemplateResolver = (
  request: WikitextTemplateRequest,
) => string | null | undefined | Promise<string | null | undefined>;

• null / undefined means the template is missing; an empty string is a valid template.
• A title is parsed once per expansion; the resolver must return stable source for the same title.
• request.pageName is the original page; request.callerTitle is the template that contains the current call and is omitted for calls on the original page.
• request.invocation points at the top-level call range in original.source; nested requests reuse that top-level range.
• The library handles newline normalization, include filtering, and parsing; the resolver only fetches source.

#Supported syntax

• Template transclusion and parameter substitution, including anonymous, named, and default values.
• noinclude / includeonly / onlyinclude.
• #if, #ifeq, #switch, #iferror.
• {{!}} and {{=}}.
• Implicit newlines around template and function output.

Values are computed only when needed: template names, parameter names, and conditions are evaluated in their own scope. Unselected branches, unread parameters, and unused defaults do not call the resolver or count toward the invocation budget.

The following calls are preserved with diagnostics by default:

• #invoke and Lua.
• Transclusion modifiers such as subst.
• Functions that depend on site state or an external runtime, such as #ifexist and #time.

#Budgets and errors

• A single over-long call is preserved with LENGTH_BUDGET_EXCEEDED.
• If even the preserved source exceeds maxExpandedLength, the library throws EXPANSION_TOO_LARGE.
• With strict: true, budget overruns throw EXPANSION_BUDGET_EXCEEDED.
• By default, a final parse failure returns the original snapshot with status: "fallback".
• Cancellation is delivered through AbortSignal; the original reason is stored in cause.

All errors are WikitextExpandError. Common codes include TEMPLATE_NOT_FOUND, TEMPLATE_LOOP, UNSUPPORTED_CALL, FINAL_PARSE_FAILED, and ABORTED.

#Results and diagnostics

const {
  original, // original parse snapshot
  document, // expanded parse snapshot
  expansion, // status / records / diagnostics
} = expanded;

• expansion.records records each call's kind, name, original range, expanded range, and status (expanded / preserved).
• expansion.diagnostics coordinates are based on original.source.
• document.diagnostics merges final parse diagnostics with expansion diagnostics mapped onto the expanded source.
• prepareWikitext(document) carries these diagnostics into the render result.

Nested calls map only to their top-level record; there is no precise source mapping inside templates.

#How preserved calls render

Templates, functions, and arguments preserved after a failed expansion continue to render as placeholders. They are never presented as evaluated content. Template source and expansion results are treated as untrusted wikitext and still go through semantic normalization, HAST conversion, and final sanitization.

#Limitations

• Include filtering is a single pass; nested noinclude / onlyinclude inside includeonly content is not recognized again.
• Lua is not executed and no site API client is built in.
• There is no cross-request template cache; implement caching in the resolver.
• Categories, references, and tables of contents in expanded output follow the normal rendering rules.