HTML Rendering

HTML Renderer

The HTML renderer converts RST documents to semantic HTML with support for report-oriented directive plugins.

Basic Usage

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

const html = renderRst(`Title
=====

This is **bold** text.

.. code:: typescript

   const x: number = 42

.. math::

   E = mc^2
`)

Directive Plugins

Plugin	Directives	Notes
`imagePlugin`	`image`, `figure`	Image embedding
`codePlugin`	`code`, `code-block`, `sourcecode`	Shiki syntax highlighting (auto-detected)
`mathPlugin`	`math`	KaTeX rendering (auto-detected)
`admonitionPlugin`	`note`, `warning`, `tip`, `important`, `caution`, `danger`, `hint`, `attention`, `error`, `admonition`	Callout boxes
`csvTablePlugin`	`csv-table`	CSV table with `:file:` or inline body
`listTablePlugin`	`list-table`	Report-friendly table syntax with `:header-rows:` and `:widths:`
`rawPlugin`	`raw`	Raw HTML passthrough
`replacePlugin`	`replace`, `unicode`	Text substitution
`containerPlugin`	`container`	Custom CSS container
`contentsPlugin`	`contents`, `toctree`	Lightweight heading TOC and explicit page-card navigation
`includePlugin`	`include`	Build-time include marker; pair with include expansion for actual reuse

Report-Oriented RST Features

This renderer intentionally prioritizes reusable report building blocks over full Sphinx compatibility.

.. list-table:: is supported for data-driven report tables
.. contents:: builds an in-document heading TOC
.. toctree:: renders explicit related-page entries, not a full doc graph
.. include:: is best treated as a preprocessing step

If you need syntax details, see RST Writing Rules.

Custom Directives

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

const renderer = new HtmlRenderer()

renderer.registerDirective('my-custom', (directive, ctx, renderChildren) => {
  ctx.write(`<div class="custom">`)
  renderChildren(directive.children, ctx)
  ctx.write(`</div>`)
})

Code Highlighting

When shiki is installed, code blocks are automatically syntax-highlighted:

pnpm add shiki

Without Shiki, code blocks render as <pre><code> with data-language attributes for client-side highlighting.

Math Rendering

When katex is installed, math blocks render as rendered HTML:

pnpm add katex

Without KaTeX, math renders as LaTeX source wrapped in <div class="math">.

Include Expansion

The renderer itself does not resolve files from .. include:: automatically. Use include expansion before parsing:

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

const html = renderRst(source, {
  includeResolver: { baseDir: process.cwd() },
})

This is designed for reusable report fragments, not full Sphinx include semantics.

HTML Rendering

On this page