Show the Working

Markdown to RST

Nothing you choose here leaves your browser, and nothing is downloaded to make it work. You can paste instead of choosing a file.

…or drop a file anywhere on this page.

Into Sphinx, which is usually why anybody wants this.

Headings get underlines in the conventional order, lists and literal blocks become their RST equivalents, and links are written anonymous — with two underscores. That last one matters: two links with the same text and a single underscore are a duplicate-target error in docutils, and a converter that writes single underscores produces a file Sphinx refuses to build.

A heading's level is not decided by its underline

=== is not “heading 1”. reStructuredText has no fixed hierarchy at all: the level of a section is decided by the order in which its underline character first appears in the document. A file that underlines its top-level sections with - and its subsections with = is perfectly correct RST, and is not unusual — several large projects write it that way.

A converter with a table mapping = to h1 turns such a document inside out: every section becomes a subsection of its own subsection. This remembers the characters in the order it meets them and uses the position in that list, which is the actual rule. The check for it uses a document with the characters the other way round and compares against docutils by way of pandoc, because a test written in the conventional order would pass with the broken version and prove nothing.

The other two that are easy to get wrong

A paragraph ending in :: announces a literal block, and the :: is not text. After a word it leaves a single colon — “as follows::” reads “as follows:” — and alone on its line it disappears entirely. Print it and you get a document littered with stray double colons, which is what a surprising number of converters do.

And .. thing:: is a directive while .. thing is a comment. One colon apart. A converter that treats them alike either prints every comment into your document or silently drops every image.

What is read, and what is not

Read: sections, paragraphs, bullet and enumerated lists to any depth, literal blocks, block quotes, transitions, field lists, inline emphasis, strong and literals, links both inline and named, images, and the directives people actually use — code-block, code, image, figure, note, warning, tip and important.

Not read: tables, in either of RST's two syntaxes, so a table's text arrives as paragraphs. Nor footnotes, citations, substitutions or include. Roles such as :ref:`name` keep their text and lose the link. A directive this does not know keeps the words inside it and reports that it did, because those words are usually yours.

Where to go next