Markdown to reStructuredText
Convert Markdown to reStructuredText for Sphinx and Python docs.
Convert Markdown to reStructuredText for Sphinx and Python docs. Paste your content and get an instant result.
Paste Markdown and this page returns reStructuredText: headings get per-level underline characters, inline code becomes double backticks, literal blocks use the double-colon marker and links use the embedded-URI form.
The underline characters follow the order the docutils specification defines, so a document with four heading levels gets four distinct underlines rather than the same character repeated, which Sphinx would warn about.
Everything runs in the tab. The output is a document intended for Sphinx or another docutils reader, and it is written as source rather than validated against a build.
Block conventions
Each heading level has its own underline character, drawn from a fixed sequence. Reusing one character at two levels is the classic way to produce a document Sphinx accepts but renders with a broken outline.
A literal block is introduced by a double colon and indented. Inline code uses double backticks, which is the native spelling rather than Markdown's single ones.
- Per-level underline characters in docutils order
- Literal blocks marked with a double colon
- Inline code as double-backtick spans
Links, images and what is lost
Links use the embedded-URI form and images use the image directive, so neither needs a separate substitution definition. Tables are emitted as a directive rather than an ASCII grid.
Constructs with no reStructuredText equivalent are written as their plain text. The output is a draft for a documentation build, and a directive's exact options may still need adjusting for a particular Sphinx theme.
How to use the converter input
Paste the Markdown into the input workspace and copy the reStructuredText: headings take per-level underline characters in the docutils order so four levels never repeat one, inline code becomes double backticks, literal blocks open with a double colon, and links and images use the embedded-URI and image directive forms. Tables are emitted as a directive.
Constructs with no equivalent are written as plain text, and a directive's exact options may still need adjusting for a Sphinx theme. The output is source for a documentation build, not a validated build result.
What to Expect
Best for
- Moving Markdown documentation into a Sphinx project
- Producing a document with a correct heading hierarchy
- Converting code-heavy notes where literal blocks matter
Not ideal for
- A build that must pass a strict docutils check unchanged
- Round-tripping reStructuredText back to Markdown
- A theme-specific table layout
What this tool keeps
- Heading hierarchy through distinct underline characters
- Code blocks as literal blocks
- Link and image destinations in RST-native form
What may need cleanup
- A directive option a particular theme requires
- A table that needs a width hint
- A construct written as plain text for lack of an equivalent
Common errors
- Assuming every Markdown construct has a direct counterpart
- Reusing one underline character for two heading levels
- Expecting a build check rather than a conversion
Example use cases
- Porting a README into Sphinx docs
- Converting release notes for a docutils build
- Learning how RST headings differ from Markdown
Sample input
Paste Markdown with two heading levels, a bulleted list and a fenced code block.
Sample output
RST with two distinct underline characters, a bulleted list and an indented literal block, downloaded as document.rst.
Who this is for
- Documentation engineers using Sphinx
- Developers porting Markdown into docs
- Anyone who needs RST source rather than Markdown
Frequently asked questions
What does Markdown to RST produce?
reStructuredText with per-level underline characters, double-backtick inline code, double-colon literal blocks and embedded-URI links.
Will the result pass a strict docutils check unchanged?
Not necessarily. A directive option or a theme-specific detail may need adjustment.
What happens to a construct with no RST equivalent?
It is written as plain text rather than dropped silently.
Build custom tools for your store
Join the SDK program to create useful ecommerce utilities for your store.