API Reference

Python API

For visitor- and plugin-style customization, see Extension API.

The main class is RestructuredText. Several aliases are provided for convenience; they are identical:

Name	Import path
`RestructuredText`	`from rich_rst import RestructuredText`
`ReStructuredText`	`from rich_rst import ReStructuredText`
`reStructuredText`	`from rich_rst import reStructuredText`
`RST`	`from rich_rst import RST`
`reST`	`from rich_rst import reST`

class rich_rst.RestructuredText(markup: str, code_theme: str | SyntaxTheme | None = 'monokai', show_line_numbers: bool | None = False, show_errors: bool | None = False, guess_lexer: bool | None = False, default_lexer: str | None = 'python', sphinx_compat: bool | None = True, filename: str | None = '<rst-document>', admonition_style: Literal['panel', 'compact'] = 'panel')[source]

A reStructuredText renderable for rich.

Parameters:

markup (str) – A string containing reStructuredText markup.
code_theme (Optional[Union[str, SyntaxTheme]]) – Pygments theme for code blocks. Defaults to “monokai”.
show_line_numbers (Optional[bool]) – Whether to display line numbers for syntax-highlighted code blocks.
show_errors (Optional[bool]) – Whether to show system_messages aka errors and warnings.
guess_lexer (Optional[bool]) – Whether to guess lexers for code blocks without specified language.
default_lexer (Optional[str]) – Which lexer to use if no lexer is guessed or found. Defaults to “python”
sphinx_compat (Optional[bool]) – Enable compatibility with Sphinx roles (func, meth, class, etc.) commonly used in Python docstrings. When enabled, these roles render as inline code instead of errors. Defaults to True for better compatibility with Python documentation.
filename (Optional[str]) – A file name to use for error messages, useful for debugging purposes. Defaults to “<rst-document>”
admonition_style (str) – How admonition directives (note, warning, versionadded, etc.) render. "panel" (default) emits a bordered Rich Panel per directive. "compact" collapses each directive to a styled inline title prefix, making the output suitable for narrow contexts such as CLI --help panels.

render_to_html(width: int | None = None, *, theme: TerminalTheme | None = None) → str[source]

Render the RST markup to an HTML string.

Parameters:

width (int, optional) – Output width in columns. Defaults to 80.
theme (rich.terminal_theme.TerminalTheme, optional) – The colour theme to use for the HTML export. Defaults to DEFAULT_TERMINAL_THEME from rich.terminal_theme.

Returns:

A self-contained HTML document.

Return type:

str

render_to_string(width: int | None = None, *, force_terminal: bool = False) → str[source]

Render the RST markup to a plain string.

This is a convenience wrapper around the full rich rendering pipeline. All options passed to the constructor (code theme, show_errors, etc.) are respected.

Parameters:

width (int, optional) – Output width in columns. Defaults to 80 when not specified.
force_terminal (bool, optional) – When True the console is created with force_terminal=True, which enables ANSI styles in the exported text. Defaults to False so that the plain-text output is style-free by default.

Returns:

The rendered markup as a plain string.

Return type:

str

render_to_svg(width: int | None = None, *, title: str = '') → str[source]

Render the RST markup to an SVG string.

Parameters:

width (int, optional) – Output width in columns. Defaults to 80.
title (str, optional) – Title shown in the SVG image header. Defaults to an empty string.

Returns:

An SVG document as a string.

Return type:

str

Command-line interface

rich-rst ships with a CLI module that renders RST files (or stdin) directly to the terminal.

Usage

python -m rich_rst PATH [options]
python -m rich_rst - [options]     # read from stdin

PATH is required unless you use --list-html-themes.

Options

Flag	Description
`-c`, `--force-color`	Force ANSI colour output even on non-terminal streams.
`--version`	Show the installed package version and exit.
`-e`, `--encoding`	File encoding (default: `utf-8`).
`-w`, `--width`	Output width in columns (auto-detected by default).
`-hw`, `--html-width`	`max-width` applied when saving HTML output (default: `1675px`).
`-t`, `--code-theme`	Pygments theme used for syntax-highlighted code blocks (default: `monokai`).
`--show-line-numbers`	Show line numbers in syntax-highlighted code blocks.
`-html`, `--save-html`	Path to save the rendered output as an HTML file.
`-r`, `--wrap`	Hard-wrap long lines.
`-s`, `--soft-wrap`	Enable soft-wrap mode (lines are wrapped by the terminal).
`-gl`, `--guess-lexer`	Guess the syntax-highlighting language for code blocks that do not specify one.
`-dl`, `--default-lexer`	Fallback language for code blocks when none is detected (default: `python`).
`-se`, `--show-errors`	Show RST parse errors and warnings.
`--admonition-style`	How to render admonitions (`panel` or `compact`, default: `panel`).
`--html-theme`	Theme for `--save-html` output. Available values: `dracula`, `monokai`, `night-owl`, `dimmed-monokai`, `default`.
`--list-html-themes`	Print available HTML themes and exit.
`-o`, `--output`	Write rendered plain-text output to a file instead of stdout.