Markdown to reStructuredText Converter

Writing for Sphinx or a Python project that uses reStructuredText? Paste Markdown and get RST back: headings gain underline adornments, code fences become code-blocks, links and images take RST roles and directives, and lists and quotes are translated. It updates as you type and stays on your machine.

How to use the Markdown to reStructuredText Converter

Paste Markdown on the left and the reStructuredText equivalent appears on the right, updating as you type. Copy RST places it on your clipboard. Headings are converted to RST's underline (and overline) style, where the character under the title marks the level — this tool uses a consistent sequence (=, -, ~, ^, ") so nesting stays predictable. Bold becomes **double-asterisk** and italic becomes *single-asterisk*, matching RST's inline markup.

Inline code uses RST's double-backtick literal syntax, and fenced code blocks become a .. code-block:: directive with the language preserved and the body indented, which is what Sphinx expects. Links are rewritten to the `text <url>`_ role, images to the .. image:: directive, and ordered and unordered lists and blockquotes are translated to their RST forms. Plain paragraphs pass through.

It all runs locally in your browser, so you can paste internal documentation without anything being uploaded, and it works offline.

Markdown versus reStructuredText

reStructuredText, almost always called RST, is the markup language at the heart of the Python documentation ecosystem. It is the native input format for Sphinx, the tool that builds the official Python docs and countless project sites on Read the Docs. If you are contributing to a Python library, its docs/ folder is very often full of .rst files, so turning a Markdown draft or an existing README into RST is a routine task. While Sphinx can also read Markdown through an extension, much existing content and many directives assume RST, so converting is frequently the path of least resistance.

The most visible difference from Markdown is how headings work. Markdown marks a heading with leading # characters that directly encode the level. RST instead underlines the title text with a row of punctuation — and the level is not fixed by which character you choose but by the order in which characters first appear in the document. The first underline style encountered becomes level one, the next new style becomes level two, and so on. A converter has to impose a consistent convention (such as = for the top level, then -, ~, and so on) and make each underline at least as long as its title, or Sphinx will warn or misnest the sections.

Inline and block syntax diverges in punctuation too. RST uses *italic* and **bold** — the reverse emphasis convention from some Markdown habits — and crucially uses double backticks for inline literals, where Markdown uses single. Links are written back-to-front compared with Markdown, as `text <url>`_, and both images and code are expressed as directives: blocks that begin with .. followed by a name, with indented content. This directive system is what gives RST its power for technical writing — admonitions, cross-references, automatic API documentation — but it also means a mechanical conversion has to restructure code and images rather than just swap a few characters. For everyday content the mapping is reliable; very rich Sphinx features have no Markdown source to convert from and are added afterward by hand.

Common use cases

  • Sphinx documentation. Convert a Markdown draft into the RST files a Sphinx project expects.
  • Python packaging. Prepare a long description or docs page in RST for PyPI or Read the Docs.
  • Contributing. Match a project that standardizes on reStructuredText when your notes are in Markdown.
  • Learning RST. See how familiar Markdown constructs map to RST syntax.

Frequently asked questions

Why are headings underlined instead of prefixed?
That is how RST marks headings — the title text is underlined with punctuation, and the level comes from the order styles appear. The converter applies a consistent =, -, ~, ^ sequence so nesting is predictable.

Why does inline code use two backticks?
RST uses double backticks for inline literals, unlike Markdown's single backtick. The converter rewrites `code` as ``code`` so it renders as a literal in Sphinx.

How are code blocks converted?
A fenced block becomes a .. code-block:: directive with the language preserved and the code indented, which is the form Sphinx renders with syntax highlighting.

Is the conversion lossless?
For common elements, yes. Advanced Sphinx directives have no Markdown equivalent to convert from, so very rich documents may need manual additions after conversion.