NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #361 most downloaded on PyPI
A beautiful reStructuredText renderer for rich
Last release 7 days ago
27 Sep 2026
Ships unpredictably
gaps range from 8 days to 1.9 years
Most releases are documented
notes for 21 of 25 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
34 releases · first in 2021
One column per quarter.
Fix arbitrary local file read through .. literalinclude:: , which accepted absolute and ../ paths ( GHSA-qf6c-j2qx-p22r ).
.. literalinclude::, which accepted absolute and ../ paths (GHSA-qf6c-j2qx-p22r)... raw:: with :file: or :url: (GHSA-qx2q-xxw7-587f). The same fix covers .. csv-table:: with :file: or :url: and the docutils include directive used when sphinx_compat=False.include and literalinclude now resolve symlinks before checking that a path stays inside the source document's directory.include, literalinclude, and raw/csv-table with :file: or :url:) are now disabled by default. Pass the new allow_file_access=True option (CLI: --allow-file-access) to enable them for trusted markup.allow_file_access option to RestructuredText and --allow-file-access CLI flag.parsed-literal directive, keeping inline markup inside the literal block.:subtitle:).attribute/property/data entries show their :type: and :value: in the title.:label: show it in the panel title.attention and danger) not filling the panel body.epigraph, highlights, and pull-quote ignoring the :class: option.|page| substitutions in them.This release brings major improvements to CI/CD automation, CLI usability, test coverage, and developer experience.
This release brings major improvements to CI/CD automation, CLI usability, test coverage, and developer experience.
-S, --save-html short flag — Shorter alias for HTML export (e.g., rich-rst file.rst -S out.html)-d, --debug flag — Enable debug logging for troubleshooting parsing and rendering issuespublish.yaml workflow
v*)workflow_dispatchlint.yaml workflow
ruff for code style and formattingmypy for type checking.pre-commit-config.yaml)
ruffmypypre-commit installdev extra — Install dev tools: pip install -e ".[dev]"
ruff, mypy, pre-committest_edge_cases.py
CODECOV_TOKEN secret to GitHub for full integrationforce_color default handling (was None, now False)pytest-coverage package, now uses pytest-cov)-S and -d flagsdocs/source/documentation.rst) with complete CLI options table-d/--debug option documentation-S as short flag for --save-htmldocs extra — Removed self-reference to rich_rst packagedev extra — ruff, mypy, pre-commit for development[tool.ruff] — Code style settings (line length 100, Python 3.8+)[tool.mypy] — Type checking configuration.pre-commit-config.yaml — Local hook configuration.github/workflows/lint.yaml — Linting and type-checking CI.github/workflows/vendor.yaml — Automated vendor updates.github/workflows/publish.yaml — Release automation.github/dependabot.yml — Dependency update automationtests/test_edge_cases.py — Comprehensive edge case tests📊 Test Coverage
⚙️ Compatibility
🙏 Contributors
📝 Changelog
Full commit history available at GitHub (v2.0.3...v2.1.0).
Include custom fixtures in sdist by @carlwgeorge in #60
Full Changelog: v2.0.2...v2.0.3
Full Changelog: https://github.com/wasi-master/rich-rst/compare/v2.0.2...v2.0.3
Fix a bug with incorrect rendering for bullet lists
Fix versionadded/changed/deprecated body leaking into panel title by @BrianPugh in #53
.. contents:: / .. topic:: rendering: panel with title and populated TOC by @Copilot in #25visit_figure handler for .. figure:: directive by @Copilot in #23Full Changelog: v1.3.2...v2.0.1
.. contents:: / .. topic:: rendering: panel with title and populated TOC by @Copilot in https://github.com/wasi-master/rich-rst/pull/25visit_figure handler for .. figure:: directive by @Copilot in https://github.com/wasi-master/rich-rst/pull/23Full Changelog: https://github.com/wasi-master/rich-rst/compare/v1.3.2...v2.0.1
Better handling for Python documentation directives for enhanced clarity and rendering
Better handling for Python documentation directives for enhanced clarity and rendering
feat: Add flat-table directive with visual cell merging (cspan/rspan) by @germa89 in #42
Full Changelog: v2.0.0a7...v2.0.0a8
New release prep for 2.0.0a7 with package discovery enabled to fix bug with vendored docutils not working.
Added a comprehensive Sphinx and reStructuredText demo gallery page.
Fixed visit_raw: _guess_lexer_name returns a tuple but was previously assigned as a scalar after stripping HTML tags, causing a TypeError with Syntax.
visit_raw: _guess_lexer_name returns a tuple but was previously assigned as a scalar after stripping HTML tags, causing a TypeError with Syntax.visit_definition_list: the len == 3 branch now uses a sub-visitor to render the definition body, preserving inline markup (bold, italic, links, etc.) instead of flattening it via astext().visit_definition_list (≥ 4 children): extra classifiers and paragraph-type definition content were silently dropped; they are now rendered correctly. Existing direct-call visitor invocations are also wrapped to prevent spurious SkipChildren propagation.visit_definition_list: the variable holding child_children[1] in the two-child branch was misleadingly named classifier; renamed to definition to match its actual role.visit_block_quote and _collect_body_renderables: both previously called astext() on child nodes, losing all inline markup. They now use a sub-visitor so bold, italic, links, and inline code are preserved inside block quotes, topics, and sidebars.visit_sidebar: used astext() across body children; replaced with _collect_body_renderables for full inline-markup fidelity._sphinx_registration_guard: the inner wrapper function lacked @functools.wraps, making the wrapped function lose its __name__, __doc__, and other introspectable attributes.RestructuredText.render_to_string(width=None, *, force_terminal=False) convenience method that renders the markup and returns the result as a plain string without needing a Console instance... literalinclude:: now reads and renders the referenced file (resolved relative to the RST source file) as a syntax-highlighted code block. The :lines:, :language:, :linenos:, and :encoding: options are supported. When the file cannot be found a graceful placeholder panel is shown as before.RSTVisitor.register_visitor(node_class, visit_fn=None, depart_fn=None) class method and corresponding dispatch_visit / dispatch_departure overrides, providing a clean mechanism for third-party code to render custom docutils nodes without subclassing... toctree:: now renders entries with path-depth indentation (entries containing / are visually indented relative to root-level entries), respects :maxdepth: to omit overly deep entries, and displays explicit Title <docname> labels.RSTVisitor is now exported in __all__ so it is part of the public API.RestructuredText.log_errors → RestructuredText.show_errors to match the constructor parameter name.test_api.py: fixed two assertions that referred to the old log_errors attribute; added tests for render_to_string and register_visitor.test_definition_list.py: relaxed over-specified structural assertions to content-presence checks after the definition-list rendering improvements.test_block_elements.py: added tests verifying that bold and italic inline markup inside block quotes produces the correct Span objects.test_new_sphinx_directives.py: added tests for toctree hierarchy / maxdepth / explicit titles, and for literalinclude reading an actual file.Improved table rendering for rowspan/colspan handling and preserved inline markup in table cells.
Register new Sphinx directives when sphinx_compat=True: versionadded, versionchanged, deprecated (styled status panels in green/cyan/yellow), deprecat…
Change hide_errors to show_errors and the CLI flag --hide-errors to --show-errors to make hiding errors the default behaviour.
Vendor docutils into rich_rst to avoid licensing issues and drop docutils as a dependency to solve licensing issues
Register new Sphinx directives when sphinx_compat=True: versionadded, versionchanged, deprecated (styled status panels in green/cyan/yellow), deprecated-removed <added> <removed> (bold red panel), and seealso (bold white panel)
Add Sphinx code directive support when sphinx_compat=True: code-block, sourcecode, and code now forward to visit_literal_block with option passthrough (,,, etc.);highlight is consumed silently
Add document-structure directives when sphinx_compat=True: toctree (panel with optional title and bullet entries),glossary (nested-parsed definition list), hlist (terminal bullet list), centered (centred bold text), productionlist (literal block), and only (always render content; expression ignored)
Add silent no-op directives to prevent spurious errors when sphinx_compat=True: index, tabularcolumns, currentmodule, py:currentmodule, and all auto* autodoc directives
Add domain object description directives when sphinx_compat=True: Python (py:function, py:class, py:method, py:attribute, py:data, py:exception, py:module, py:property, py:decorator, py:classmethod, py:staticmethod, py:variable, py:type, py:typevar, py:typealias), C (c:function, c:type, c:struct, c:union, c:enum, c:enumerator, c:member, c:var, c:macro), C++ (cpp:function, cpp:class, cpp:type, cpp:member, cpp:var, cpp:enum, cpp:enumerator, cpp:concept, cpp:alias), and JavaScript (js:function, js:class, js:method, js:attribute, js:data, js:module) — each rendered as a panel with the signature as title and docstring body as content
Register new Sphinx roles when sphinx_compat=True: rendersPEP <n> as a clickable link to peps.python.org, rendersRFC <n> as a clickable link to datatracker.ietf.org
Add role rendering support when sphinx_compat=True: andrender bold text;renders italic/emphasis;with expansion reusesvisit_abbreviation
Add role rendering support when sphinx_compat=True: renders as inline literal and converts--> to ▶; andrender as inline literal with{placeholder} markers stripped
Add inline-literal cross-reference role support when sphinx_compat=True for all c:*, cpp:*, and js:* roles plus ,,,,,,,:any:, and related Sphinx cross-reference roles
Add show_line_numbers parameter to RestructuredText and the CLI (--show-line-numbers); applies to all syntax-highlighted blocks (literal, doctest, raw
show_line_numbers parameter to RestructuredText and the CLI (--show-line-numbers); applies to all syntax-highlighted blocks (literal, doctest, raw)visit_figure handler for the .. figure:: directive; renders image, caption and legend inside a panel, with correct link when :target: is givenvisit_table handler for RST grid and simple tables, including optional caption/title and proper header row supportvisit_topic handler, rendering topics (including auto-generated table of contents) as a bordered panelvisit_footnote_reference to render inline [N] footnote markers inline with the surrounding textvisit_title_reference (the backtick title role) rendered in italicvisit_substitle_reference to render substitution references.docinfo bibliographic-field handlers: author, authors, organization, address, contact, version, revision, status, date, copyright — all rendered in the shared field tableDocTitle and DocInfo transforms so recognised metadata fields are promoted to typed docinfo nodes before rendering_render_admonition_body helper: all admonition types (note, warning, tip, hint, attention, caution, danger, error, important, generic) now render their body through a sub-visitor, preserving inline markup (bold, italic, code, links, etc.) instead of stripping it to plain textvisit_bullet_list and visit_enumerated_list as recursive _render_bullet_list / _render_enumerated_list methods, supporting unlimited nesting depth, correct per-level indentation and markers (•, ∘, ▪), and arbitrary child node types including literal blocksvisit_rubric as a distinct handler with an italic-dim rounded-box panel (previously delegated to visit_title)_make_image_text helper; images wrapped in a reference node (e.g. inside a figure) correctly use the outer link URIGroup(*visitor.footer)visit_paragraph re-entering visit_system_message without stopping — now raises SkipChildren immediatelyvisit_line_block not preserving nested indentation — now uses a recursive _render_line_block helper.astext().replace("\n", " ")visit_system_message raising KeyError for unrecognised message types (SEVERE, DEBUG, unknown) — changed dict[key] lookup to .get(key, "bold red")visit_field raising IndexError when renderables is empty — added a truthiness guard before inspecting the last elementvisit_option_list raising TypeError when concatenating Text with "" — changed the fallback to Text()visit_sidebar raising IndexError when subtitle is absent — now safely handles one-child or subtitle-less sidebar nodesvisit_raw raising ClassNotFound / IndexError — delegate lexer guessing to the shared _guess_lexer_name helpervisit_math_block calling non-existent self.renderables.append_text() in the else branchvisit_pending — handler was misspelled as visit_pendingsvisit_problematic missing raise SkipChildren(), causing double-renderingText.from_markup with user-supplied classifier text, allowing Rich markup injection — replaced with Text(term, style=...)supercript → superscript)_register_sphinx_roles() registering roles repeatedly on each render — guarded with a module-level _sphinx_roles_registered flagvisit_footnote and visit_generated output being centre-aligned — changed to left-alignedGroup:target: is set--show-line-numbers flag to display line numbers in syntax-highlighted code blocks<html> before <head>, and replaced <code><pre> with the correct <pre><code> nestingwith statement--save-html KeyError in __main__.py (f-string left bare CSS braces that broke Rich's internal format() call)Convert to pyproject.toml, use setuptools_scm to manage version. by @BrianPugh in https://github.com/wasi-master/rich-rst/pull/15
Full Changelog: https://github.com/wasi-master/rich-rst/compare/v1.3.1...v1.3.2
Remove trailing empty Text() objects that get displayed as newlines. by @BrianPugh in https://github.com/wasi-master/rich-rst/pull/14
Full Changelog: https://github.com/wasi-master/rich-rst/compare/v1.3.0...v1.3.1
Fix docutils/optparse deprecation warnings by @BrianPugh in https://github.com/wasi-master/rich-rst/pull/10
Full Changelog: https://github.com/wasi-master/rich-rst/compare/v1.2.0...v1.3.0
Add rich dependency by @davidbrochart in https://github.com/wasi-master/rich-rst/pull/3
__main__.py by @wasi-master in https://github.com/wasi-master/rich-rst/commit/8f63f3a5db115879ad06954e05efc8f9f82352e3Full Changelog: https://github.com/wasi-master/rich-rst/compare/v1.1.7...v1.2.0
Fix the entire text being shown as an inline code-block when only the first text is
Fix an issue where if a document started with bare text (not headers) then it would crash
Fix a debug print message showing up
Doctest blocks now use the pycon lexer rather than the default python lexer since the pycon lexer is specially made for console sessions
pycon lexer rather than the default python lexer since the pycon lexer is specially made for console sessionspycon lexer rather than the default python lexer since the pycon lexer is especially made for console sessionsChange caution style from white on red to just red
white on red to just redRestructuredText classreST<string>Admonitions are now shown inside panels
Add support for citations and citation references
Add support for acronym
Add support for attribution
Add support for citations and citation references
Add support for decoration
Add support for footers
Add support for headers
Add support for footnotes
Add support for more elements in definition lists and improve formatting
Add subscript and superscript support for some letters and symbols
Add support for pending
Add support for raw
Add custom default lexer support
Add support for guessing the lexer
Add support for the rubric element
Add support for most of the elements possible
Nothing published for this version
Add code_theme parameter support for code blocks
code_theme parameter support for code blocksNothing published for this version
Fixed a bug with images without alt not being shown
Nothing published for this version
- Small documentation fixes
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →