rst-renderer

reStructuredText renderer for JavaScript/TypeScript — RST → HTML, React, Markdown

Overview

rst-renderer is a TypeScript library for report-oriented reStructuredText: parse RST into a unified AST, render it to HTML / React / Markdown, and generate final reports from Jinja2-style templates plus external project data.

Quick Start

pnpm add @seqyuan/rst-renderer

import { renderRst } from '@seqyuan/rst-renderer'

const html = renderRst(`Hello
=====

This is **bold** and *italic* text.

- item 1
- item 2
`)

Packages

Package	Description	npm
`@seqyuan/rst-renderer`	Core: parser + HTML/React/Markdown renderers + template engine	`pnpm add @seqyuan/rst-renderer`
`@seqyuan/rst-cli`	CLI: template rendering, JSON vars, wildcard scans, standalone HTML	`pnpm add -g @seqyuan/rst-cli`
`@seqyuan/vite-plugin-rst`	Vite: `import html from './doc.rst'`	`pnpm add -D @seqyuan/vite-plugin-rst`

Architecture

RST Source
    │
    ▼
┌─────────────┐
│   Parser    │  ← builtin parser / rst-compiler adapter
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Unified AST │  ← 40+ node types (Document, Section, Paragraph, Table...)
└──────┬──────┘
       │
       ├──→ HTML Renderer    (report-oriented directive plugins, Shiki, KaTeX)
       ├──→ React Renderer   (custom component mapping)
       └──→ Markdown Renderer (GFM tables, heading offset)

Features at a Glance

Category	Feature	Status
Parsing	Sections, paragraphs, lists, tables, directives, comments	✅
	Inline markup: bold, italic, code, links, references	✅
	Builtin parser + rst-compiler adapter	✅
HTML	Semantic HTML with CSS classes	✅
	Report-oriented directives: image, admonition, csv-table, list-table, contents/toctree, include	✅
	Shiki syntax highlighting (auto-detect)	✅
	KaTeX math rendering (auto-detect)	✅
React	Component tree generation	✅
	Custom component overrides per node type	✅
Markdown	GFM table output	✅
	Heading offset customization	✅
Templates	Jinja2-compatible syntax	✅
	Nested for/if/else, 12 filters, loop variables	✅
CLI Reports	JSON data + `-v` overrides + `--scan name=glob`	✅
	Optional `--expand-includes` and standalone HTML bundling	✅
CJK	Full Chinese/Japanese/Korean support	✅
Types	Full TypeScript definitions (ESM + DTS)	✅

Design Scope

This project does not aim to be another Sphinx.

It focuses on report generation, application embedding, and pipeline output rendering
contents, toctree, and include are intentionally implemented in a lightweight way
The recommended workflow for complex reports is: RST template + external variables + wildcard scans

Usage Scenarios

New to rst-renderer? Start with the Quick Start guide.

Documentation sites — Render RST documentation to HTML at build time (see also Vite Plugin).

import { renderRst } from '@seqyuan/rst-renderer'
import fs from 'node:fs'

const rst = fs.readFileSync('README.rst', 'utf-8')
const html = renderRst(rst)

Bioinformatics reports — See the full Bioinformatics Report Tutorial. Quick CLI workflow:

rst-render report.rst.j2 \
  -t \
  -d project.json \
  --scan plots=upload/plots/*_umap.png \
  --expand-includes \
  -o report.html -s

React apps — Render RST content as React components.

import { ReactRenderer } from '@seqyuan/rst-renderer/react'

const renderer = new ReactRenderer({
  components: {
    Section: ({ node, children }) => (
      <section className="my-section">
        <h2>{node.title}</h2>
        {children}
      </section>
    ),
  },
})

Vite projects — Import .rst files directly. See Vite Plugin.