reStructuredText converter
Convert reStructuredText files with care for Sphinx directives, roles, tables, includes, references, and document outputs.
.rst
Format
About reStructuredText
reStructuredText, often shortened to RST, is a plaintext markup format from the Python documentation ecosystem. It represents headings, paragraphs, lists, literal blocks, tables, hyperlinks, footnotes, citations, directives, and interpreted text roles using indentation and punctuation. RST is more structured than basic Markdown and pairs closely with docutils and Sphinx. It is common in Python packages, API docs, Read the Docs projects, and technical manuals that need cross references or generated indexes. Our document routes convert RST to Markdown, HTML, DOCX, ODT, RTF, LaTeX, EPUB, TXT, and PDF, and can write RST from several document sources through Pandoc.
Version details usually mean toolchain details. Core reStructuredText syntax comes from docutils, while Sphinx adds many directives and roles such as automodule, toctree, ref, doc, and intersphinx references. A converter that is not running the full Sphinx build may see those extensions as unknown blocks. Include directives depend on local files. Substitutions, grid tables, list tables, image options, admonitions, and code-block metadata all need syntax-aware handling. Plain text remains readable in version control, but small indentation mistakes can change nesting or make a directive part of the wrong section. Project configuration decides how much of that meaning appears.
Readers and writers include Sphinx, docutils, Pandoc, Read the Docs, Python package tooling, documentation editors, and source repositories. Writers choose RST when they need stronger cross-reference semantics than simple Markdown or when a project already builds with Sphinx. Reviewers may request HTML or PDF for reading, DOCX for comments, or Markdown for migration to another site generator. The best conversion path depends on whether Sphinx-specific behavior is part of the document or whether the file uses mostly portable core syntax. Those build assumptions should be captured before migration begins early.
RST conversion breaks when project context is missing. RST to HTML through a generic converter will not resolve Sphinx inventories, generated API pages, or toctree navigation. RST to Markdown loses some directive semantics and may simplify tables. RST to DOCX is useful for reviewers but does not preserve build-time links or custom roles perfectly. RST to PDF typesets a fresh document rather than imitating a Sphinx theme. Before converting, build or inspect the source project, gather included files and images, note custom roles, and test a page with code blocks, tables, and cross references.
Common reStructuredText problems
Sphinx directives show up as plain text after conversion.
Use /convert/rst-to-html only for portable RST, or build with Sphinx first when directives drive the page.
Documentation is moving to a Markdown site generator.
Use /convert/rst-to-md, then manually rewrite roles, substitutions, and toctree navigation.
Reviewers want to comment in Word.
Use /convert/rst-to-docx, then check code blocks, footnotes, admonitions, and tables.
A printable copy is needed from source docs.
Use /convert/rst-to-pdf, then compare headings and code wrapping against the documentation team's style.
LaTeX tooling is the publishing target.
Use /convert/rst-to-latex, then repair packages and macros expected by the receiving TeX template.