reStructuredText ↔ Markdown
Convert reStructuredText to Markdown — and back — for Sphinx / Python docs
Translate headings, code blocks, inline literal, links, and images between rST and Markdown. Useful for Python project migrations and cross-platform docs imports. Runs entirely in your browser.
Converting Markdown → reStructuredText
Covers headings, inline formatting, code blocks, links, and images. Cross-references, substitutions, and conditional content require Pandoc.
When you need this converter
- Migrating a Python project's docs from rST to Markdown (or MyST).
- Contributing to a Sphinx-based project that still uses rST.
- Importing third-party rST documentation into an MDX-based docs site.
What gets converted
| Markdown | reStructuredText |
|---|---|
# H1 | Heading with = underline |
## H2 | Heading with - underline |
\code`` | |
```lang | .. code-block:: lang + indented body |
[text](url) | `text <url>`_ |
 | .. image:: url with :alt: alt |
| Bullets | * bullets (no change) |
Reverse maps the equivalent rST constructs back to Markdown.
Companion tools
- AsciiDoc ↔ Markdown — for AsciiDoc workflows.
- Markdown to Confluence — for Atlassian docs.
- Markdown Editor — write Markdown with live preview.
Privacy & data
The converter runs inside your browser. No content is uploaded.
Frequently asked questions
- reStructuredText (rST) is a markup format from the Python community, used by Sphinx, Read the Docs, and most Python project documentation. It supports directives (`.. code-block::`), cross-references, and rich semantic markup beyond plain Markdown.
- Many Python projects are migrating from rST to MyST Markdown for friction-free contributions. The reverse — Markdown to rST — is useful when contributing patches to projects that still use rST. This tool handles the common cases without installing Pandoc.
- Headings with underline (`=== / --- / ~~~ / ^^^ / """`), code blocks (`.. code-block:: lang` indented), inline literal (`` ``code`` ``), hyperlinks (`` `text <url>`_ ``), and image directives. Complex features (cross-references, substitutions, conditional content) are not supported — use Pandoc for those.
- MyST is a Markdown dialect that supports rST-flavored directives. It's a strong choice for new Sphinx-based projects because it gets you Markdown ergonomics with rST-level power. This converter targets pure rST; for MyST, you can usually keep your Markdown as-is.
- Pandoc is the comprehensive solution for cross-format conversion — install it for batch processing or for the long tail of edge cases. This page is for one-off conversions without any setup.
- No. Conversion runs entirely in your browser.