reStructuredText to Markdown Converter

reStructuredText is the markup behind Python’s documentation, Sphinx and Read the Docs, and many Python projects still ship a README.rst. Markdown is what GitHub, MkDocs, Docusaurus and most static site generators expect. Converting by hand is slow because the two languages express the same ideas differently. This converter handles the common constructs and tells you what it could not translate.

Headings and levels

reStructuredText has no fixed character for each heading level. A title can be underlined with =, -, ~ or many other characters, with or without an overline, and the level is decided by the order in which styles first appear in the file. The converter follows the same rule: the first style it meets becomes #, the second ##, and so on.

Links, targets and substitutions

Inline links such as `Python <https://python.org>`_ become Python. Named targets defined anywhere in the file, like .. _API: https://example.com/api, are resolved so that API_ becomes a link. Anonymous links with double underscores, footnotes ([1]_ becomes a Markdown footnote) and substitutions such as |name| defined with replace or image are converted too.

Code and literal blocks

A paragraph ending in :: introduces a literal block, which becomes a fenced code block (“Example::” becomes “Example:”). Code-block and sourcecode directives keep their language, so python highlighting survives, and doctest blocks starting with >>> become Python code.

Directives

Notes, tips, warnings, important and caution blocks become GitHub alerts, such as > [!NOTE]. Images and figures become Markdown images, with figure captions in italics. Raw HTML is passed through. A contents directive becomes a toc marker that the Markdown TOC Generator can fill, and a toctree becomes a list of links to the .md files. Version-added and deprecated notes become italic sentences.

Tables

All four table types are converted to pipe tables: grid tables drawn with +—+, simple tables with ===== rules, list-tables and csv-tables. Cells spanning several columns cannot be expressed in Markdown and are kept in the first column they cover.

Sphinx roles

Inline code roles such as :func: and :class: become code spans, :math: becomes $…$, and :ref: and :doc: become ordinary links whose targets you may need to point at the right file. Unknown roles keep their text, and a note says so.

What is dropped

Directives that need the rest of the project — autodoc, include and literalinclude — cannot be followed in a single file; they are dropped or replaced with a comment, and listed in the notes under the output.

A worked example

The sample Quickstart page becomes # Quickstart with a fenced pip command, links to the user guide and API, a > [!NOTE] alert, a Python code block, a flag table and Author: Ana Souza from the field list.

Converting a whole documentation folder

Convert files one at a time and keep the same file names with .md extensions, so the links made from toctree and :doc: entries point to the right places. Then build the new site and follow its broken-link report; cross-references between files are the part most likely to need hand fixes.

Related tools

Preview the Markdown as HTML with Markdown to HTML, edit it in the Markdown Editor, or convert pasted grid tables separately with the ASCII Table Converter.