RST to MD Converter

What happens when you convert RST to MD

• The reStructuredText is read by pandoc, the open-source document converter, on our conversion server: headings, lists, tables, links, emphasis, code blocks and footnotes, and written as GitHub-flavoured Markdown.
• The converter reads nothing but the file itself, so images linked from it are left out; only images embedded in the file as data URIs are kept. Raw HTML inside the file is dropped.
• Directives Markdown has no equivalent for, such as note and warning boxes, become small HTML blocks inside the Markdown. Sphinx-only directives such as toctree and autodoc do nothing outside Sphinx.
• This conversion runs on our server: the file is uploaded, converted, and deleted together with the result as soon as the result has been sent back to you. Nothing is kept. Files up to 25 MB are accepted.

How to convert RST to MD online

1. Press "Choose RST files" and select one or more files, or drag them onto the box. Files up to 25 MB each can be converted.
2. There are no settings to choose: the converter keeps everything the target format can hold.
3. Press "Convert to MD". The file is uploaded to our conversion server, converted in a few seconds, and deleted together with the result as soon as the result is sent back.
4. Save each MD with its download button. Our server has already deleted both your RST and the MD by then.

Why convert RST to MD?

RST files usually come from Python documentation, Sphinx sites and README files. People convert them to MD because Markdown is readable as it is and fits wikis, documentation sites and note apps such as Obsidian.

In short, RST is good at what it was made for, and MD is the more practical choice when the file has to open, upload or print somewhere else. RST shows as plain text in browsers; Sphinx, GitHub and many code editors render it, while MD shows as plain text in browsers; editors such as Obsidian, Typora and VS Code render it.

How to convert RST to MD on Windows, Mac, iPhone and Android

On Windows

Open this page in Chrome, Edge or Firefox, drag your RST files in from File Explorer, and press Convert. Each MD is saved to your Downloads folder.

On a Mac

Safari, Chrome and Firefox all work. Drag the RST files from Finder onto the drop zone and the MD files land in Downloads.

On iPhone and iPad

Open the page in Safari and tap Choose RST files. You can pick from Photos or from the Files app. The converted MD appears in Files, in the Downloads folder.

On Android

Open the page in Chrome, tap Choose RST files and pick them from Files or your gallery. The MD is saved to the Download folder, where any file manager can find it.

Best settings for RST to MD

There are no settings: pandoc writes standard, tidy MD that any editor reads.

If something is missing, check whether it depended on a file outside the RST; the converter reads the file alone.

RST vs MD: the differences

About RST and MD files

What is an RST file?

reStructuredText is the plain-text markup of the Python world: headings are underlined with = or - characters, and directives add notes, images and code. Sphinx builds the documentation of Python itself, and of thousands of other projects, from RST files.

What is an MD file?

Markdown marks formatting with plain characters: # for headings, * for lists and emphasis. It reads naturally as text and converts cleanly to HTML, which is why developers and note apps use it.

RST to MD not working? Common problems

• "Files up to 25 MB can be converted." Server conversions have a size limit. Compress the images inside the file, or split it, and try again.
• "The conversion took too long and was stopped." Very long or complex files can pass the 90 second limit. Split the file and convert the parts.
• "This file is not really in RST format." The converter checks every file before it runs anything, so a file of another format renamed to .rst is refused. Choose the page for its real format.

Convert RST to MD from the command line

pandoc does the same on your own computer:

pandoc input.rst -t gfm -o output.md

Converting on your own computer keeps the file entirely local, which is worth it for very large or very sensitive documents. For everything else, the converter on this page does it without installing anything.