Markdown to reStructuredText

Convert Markdown to RST for Sphinx documentation and Python projects.

Markdown Input

or drop a file here

RST Output

Markdown vs reStructuredText (RST)

reStructuredText (RST) is the native documentation format for the Python ecosystem. Tools like Sphinx (the Python documentation builder) and Read the Docs natively parse RST, making it the standard for Python package docs, PEPs, and open-source project documentation. While Markdown is simpler and more widely recognized in the general web development world, RST offers richer cross-referencing, directives, and semantic markup that Sphinx exploits for navigation, indexing, and API docs. Use this converter when migrating a project from GitHub README-style Markdown to a full Sphinx documentation setup. Headings use underline characters (=, -,~), links use the `text <url>`_ syntax, and code blocks use the .. code-block:: directive.

Built and maintained by Meet Shah · Last updated 28 July 2026

What this tool is used for

Moving documentation into a Sphinx project that expects reStructuredText.
Converting a README for a Python package's documentation build.
Adapting Markdown notes for an RST-based toolchain.
Producing RST from a source maintained in Markdown.
Seeing where RST's stricter indentation rules will need the source reflowed.

Frequently Asked Questions

Why would I need RST at all?: Because Sphinx, the Python documentation toolchain, is built on it — PEPs, the standard library docs and most Read the Docs sites are RST. It buys cross-referencing, directives and a real index, which Markdown has no native equivalent for. That is the trade for the heavier syntax.
How do headings convert?: From `#` prefixes to underlines: a row of `=` under the text for level one, `-` for level two, `~` for level three. RST infers the level from the ORDER underline characters first appear in the document rather than from a fixed table, so the convention only holds if you stay consistent.
What happens to links?: `[text](url)` becomes `` `text <url>`_ `` — backticks, angle brackets around the URL, trailing underscore. That underscore is what makes it a reference rather than literal text, and omitting it is the commonest way a converted document renders raw markup where a link should be.
How are fenced code blocks handled?: As a `code-block` directive with the language preserved, followed by an indented body. RST has no fence characters — the indentation IS the block — so the closing fence disappears and the content shifts right, which is why code nested inside a list item needs checking by hand.
What will not survive the conversion?: Raw HTML blocks, which RST can only carry inside a `raw` directive, and Markdown extensions with no RST counterpart: task lists, differing footnote syntaxes, and reference-style link definitions. Inline emphasis, lists, quotes, tables and horizontal rules all convert cleanly.

Common errors and gotchas

Getting heading underline lengths wrong, since RST requires them to be at least as long as the title.
Assuming indentation is cosmetic, when RST treats it as structural and is strict about it.
Losing directives and roles, which have no Markdown equivalent to convert from.
Overlooking that RST needs a blank line before and after a literal block.
Expecting inline HTML to pass through, which RST handles through a raw directive instead.