@react-rst/parser

A lightweight, zero-dependency reStructuredText (rST) parser written in pure TypeScript. It transforms rST text into an abstract syntax tree adhering to the unist specification.

Works in all JavaScript environments: Node.js, browsers, Bun, Deno, and edge runtimes (Cloudflare Workers, Vercel Edge).

Installation

npm install @react-rst/parser

Usage

import { parse, formatDiagnostic } from '@react-rst/parser';

const rst = `
Getting Started
===============

Here is a paragraph with **bold** text and a link to Python_.

.. _Python: https://python.org
`;

const { ast, diagnostics } = parse(rst, {
  sourceId: 'docs/getting-started.rst',
});

// The parser never throws exceptions; inspect diagnostics for warnings:
for (const diagnostic of diagnostics) {
  console.warn(formatDiagnostic(diagnostic));
}

console.log(JSON.stringify(ast, null, 2));

Options

parse(content, options?) accepts:

| Option | Type | Default | Description | |---|---|---|---| | sourceId | string | undefined | Source document identifier (e.g. filename) attached to AST nodes and diagnostics. | | idPrefix | string | undefined | Prefix prepended to generated anchor IDs. | | tabWidth | number | 8 | Tab stop width (standard rST uses 8). | | directives | Record<string, DirectiveSpec> | {} | Custom directive parsers. | | roles | Record<string, RoleSpec> | {} | Custom interpreted text role parsers. | | knownDirectives | string[] | [] | List of known directives to prevent emitting RST2001 (unknown directive) warnings. | | knownRoles | string[] | [] | List of known roles to prevent emitting RST4001 (unknown role) warnings. |

Diagnostics & Logging

@react-rst/parser guarantees non-throwing execution. When syntax errors, malformed directives, or unresolved references occur, they are recorded in the diagnostics array:

• CLI/Console: formatDiagnostic(d) produces a standard greppable line:

  [react-rst] RST1001 warning docs/guide.rst:12:1 Title underline too short: expected 15 characters, got 4

• Cloud Log Services: Diagnostic objects include code, severity, sourceId, and start/end position offsets, ready for JSON logging to Google Cloud Logging, AWS CloudWatch, or Datadog.

See the full Diagnostics Reference for code definitions (RST1001 through RST9001).

License

MIT © Joshua Lauinger