> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Parsing `/parse`

```ts
import {
  createWikiparser,
  parseWikitext,
  createWikitextParser,
  WikitextParseError,
  DEFAULT_MAX_SOURCE_LENGTH,
} from "react-wikitext/parse";
```

`/parse` loads the default parser (the `wikiparser-node@1.48.1` browser bundle) and does not load React. Parsing is synchronous.

## parseWikitext

```ts
const document = parseWikitext(source, {
  pageName: "Example",
  retainSyntax: false,
});
```

Uses the shared parser with default configuration; suitable for one-off parsing and simple scenarios.

## createWikiparser

```ts
const parser = createWikiparser({
  config: MEDIAWIKI_CONFIG,
  defaults: { pageName: "Example" },
});

const document = parser.parse(source, { maxSourceLength: 50_000 });
```

- The default config is `MEDIAWIKI_CONFIG`, a snapshot of the `wikiparser-node@1.48.1` site configuration.
- Configuration is deep-cloned and normalized when the factory is created; later mutations of the original object do not affect the parser.
- Changing config requires creating a new parser.
- The library does not export a minimum config. For custom config, copy the default and adjust fields.

## Parse options

```ts
interface WikitextParseOptions {
  pageName?: string;
  maxSourceLength?: number; // default 100_000
  maxSyntaxNodes?: number; // default 50_000
  maxSemanticNodes?: number; // default 50_000
  maxDepth?: number; // default 1_000
  retainSyntax?: boolean; // default false
}
```

| Option             | Description                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| `pageName`         | Page context (for example, page names in templates or magic words); the library never invents one |
| `maxSourceLength`  | Maximum length after LF normalization                                                             |
| `maxSyntaxNodes`   | Maximum syntax tree nodes                                                                         |
| `maxSemanticNodes` | Maximum semantic AST nodes                                                                        |
| `maxDepth`         | Maximum syntax tree depth                                                                         |
| `retainSyntax`     | Keep the source syntax tree in the document                                                       |

Effective budgets merge in this order: per-call options → factory `defaults` → shared defaults. CRLF / CR is normalized to LF before parsing, and budgets are checked after normalization.

`retainSyntax` significantly increases memory and build cost; enable it only for source positions or the playground syntax tree.

## Returned document

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

`meta` contains:

- `parser` / `parserVersion`.
- `pageName`.
- `astSchemaVersion` and optional `syntaxSchemaVersion`.
- `sourceNormalized`, `originalLength`, and `retainSyntax`.

The same source with a different config or `pageName` can produce a different AST; those are parse inputs, not render options.

## Custom adapter

`createWikitextParser` does not load the default IIFE, which makes it suitable for other parsers:

```ts
import { createWikitextParser, type WikitextParserAdapter } from "react-wikitext/parse";

const adapter: WikitextParserAdapter = {
  name: "my-parser",
  version: "1.0.0",
  parse(source, context) {
    // Must return a plain object matching WikitextSyntaxRoot.
    // Ranges are based on LF-normalized source, 1-based line/column + 0-based offset.
    return buildSyntaxRoot(source, context);
  },
};

const parser = createWikitextParser(adapter, {
  defaults: { pageName: "Example" },
});
```

- The adapter only maps source → syntax tree; normalization, budget merging, semantic AST construction, diagnostics, and meta are handled by the factory.
- `context.limits` provides the effective `maxSyntaxNodes` and `maxDepth` so adapters can stop early.
- The factory still validates structure, ranges, and budgets after the adapter returns.
- The adapter's `name` / `version` are written to document meta.

## Errors

```ts
class WikitextParseError extends WikitextError {
  constructor(
    code:
      | "SOURCE_TOO_LONG"
      | "SOURCE_TOO_COMPLEX"
      | "INVALID_CONFIG"
      | "PARSE_FAILED"
      | "PARSER_UNAVAILABLE",
    message: string,
    options?: { cause?: unknown },
  );
}
```

| Code                 | Condition                                             |
| -------------------- | ----------------------------------------------------- |
| `SOURCE_TOO_LONG`    | Normalized source exceeds the length budget           |
| `SOURCE_TOO_COMPLEX` | Node count or depth exceeds the budget                |
| `INVALID_CONFIG`     | Site config is missing required fields                |
| `PARSE_FAILED`       | Upstream parsing or semantic construction failed      |
| `PARSER_UNAVAILABLE` | The default IIFE did not initialize the global parser |

Node and depth limits are internal guardrails. The effective values appear in `error.message` when triggered and are not exported as constants.

## Related

- Querying, serialization, and node types are in [`/ast`](/api/ast.md).
- Config constants are in [`/configs`](/api/configs.md).
- For workers or caching, parse in a worker and serialize the result back.