What is reStructuredText and why does Sphinx use it?

reStructuredText (RST) is the markup language Python documentation is written in. Sphinx, the tool behind the official Python docs and most Read the Docs sites, reads .rst files and renders HTML, PDF and ePub from them. RST supports directives like .. code-block:: and .. image::, cross references and a roles system that Markdown lacks, which is why large doc trees pick it. A line such as 'Install ' followed by a row of equals signs becomes a top-level heading.

How are headings written in RST?

RST headings have no leading marker. You write the title text on one line, then an underline row of a single punctuation character on the next line, and that row must be at least as wide as the title. This tool maps # to an equals underline, ## to a hyphen underline and ### to a tilde underline. So '# Setup' becomes a line 'Setup' followed by '=====', five equals signs to match the five letters. The character you choose defines the level by order of first appearance in the document.

Why is inline code two backticks in RST?

Markdown wraps inline code in a single backtick, like `value`, but RST uses two backticks, like ``value``. A single backtick in RST is an interpreted-text role, not literal code, so pasting Markdown code spans straight into a .rst file silently changes their meaning. The converter doubles every backtick pair for you, turning `npm build` into ``npm build`` so the text renders as monospaced literal code in Sphinx.

How do links differ between Markdown and RST?

Markdown writes a link as [text](url). RST writes the same link as a phrase reference: a backtick, the link text, a space, the URL inside angle brackets, a closing backtick, then a trailing underscore, giving `text `_. The angle brackets and the underscore are both required. This tool rewrites [docs](https://example.com) into `docs `_ for you, including the trailing underscore that is easy to forget by hand.

What happens to fenced code blocks and images?

A fenced Markdown block such as three backticks, python, then the code, becomes a .. code-block:: python directive with a blank line and the body indented three spaces, which is how Sphinx highlights code. A block with no language becomes a bare .. code-block:: directive. A standalone image line ![alt](url) becomes a .. image:: url directive with an :alt: option line, the RST way to embed an image into a documentation page.

Move a README into a Sphinx doc tree

Your project README is Markdown, but the docs site is built with Sphinx and expects .rst. Paste the README here, get RST with the headings underlined, the code fences turned into code-block directives and the links rewritten as `text `_, then drop the result into docs/intro.rst. No hand-editing every backtick and every link by hand.

Port a GitHub wiki page to Read the Docs

A team wiki page written in Markdown needs to live on Read the Docs, which renders RST. Convert the page in one paste, keep the bullet lists and block quotes intact, and the image at the top becomes a proper .. image:: directive instead of a broken ![]() that RST would render as literal text.

Draft docs in Markdown, ship them as RST

You think faster in Markdown — it is what your editor previews and what your notes are in. Write the page in Markdown, paste it here, and commit the RST output to the Sphinx repo. You keep the authoring speed of Markdown and the toolchain keeps the RST it expects.

Fix code spans that broke after a paste

Someone pasted Markdown straight into a .rst file and every `code` span lost its meaning because RST needs double backticks. Run the original Markdown through here and the inline code comes out as ``code``, so the literal monospaced rendering is restored across the whole page.

Markdown to reStructuredText Converter

Convert Markdown to RST for Sphinx and Python docs, with matched heading underlines, double-backtick code and `text <url>`_ links, in the browser

Runs locally
Category Format Converter
Best for Turning pasted content or local files into a handoff-friendly format.

Sphinx and most Python docs read reStructuredText, not Markdown. Paste your Markdown on the left — headings, **bold**, *italic*, `code`, fenced blocks, links, images, lists and quotes — and get RST on the right, ready to drop into a .rst file. Everything runs in this tab.

Markdown

reStructuredText242 chars

Getting started
===============

Install **toolora** and read the `docs <https://toolora.com/docs>`_.

- Fast
- *Client-side*
- ``pip install toolora``

   Built for Sphinx authors.

.. code-block:: python

   from toolora import run
   run()

What this tool does

Free Markdown to reStructuredText converter for Sphinx, Read the Docs and any Python project whose documentation lives in .rst files. Paste Markdown on the left and read clean RST on the right. The tool rewrites every construct that differs between the two formats: an ATX heading becomes a title line with a punctuation underline that is sized to match the title width, inline `code` becomes double-backtick ``code``, a [text](url) link becomes the RST `text <url>`_ form, a fenced block becomes a .. code-block:: directive with a three-space indented body, and a standalone image becomes a .. image:: directive. Bold and italic are left alone because RST already uses **bold** and *italic*. Lists, ordered numbers and block quotes carry over. Everything runs in your browser tab, with one-click copy and a shareable link that reproduces your input.

Tool details

Input: Files + Text + Numbers; The page exposes text boxes, numeric controls, file pickers, or structured inputs depending on the tool.
Output: Live result + Copy + Preview; The result area focuses on usable output, with copy, download, or preview actions when supported.
Privacy: Browser-side processing; The main tool logic does not call an external API, so inputs normally stay in the current tab.
Save / share: Shareable URL state; Key settings are encoded in the URL so another person can reopen the same setup.
Performance budget: Initial JS <= 9 KB; No WASM budget is declared, keeping the tool quick to open on mobile.
Best fit: Format Converter · Developer; Category and role tags drive related tools, internal links, and quick fit checks.

How to use

1. Input

Paste or drop your content into the tool panel.
2. Process

Click the button. All processing is local in your browser.
3. Copy / Download

Copy the result or download to disk in one click.

How Markdown to reStructuredText fits into your work

Use it when the main problem is getting content from one practical format into another.

Conversion jobs

Turning pasted content or local files into a handoff-friendly format.
Previewing a conversion before you use it in a larger workflow.
Cleaning small format mismatches without opening a full editor.

Conversion checks

Try a small sample first when the source format is messy.
Check character encoding, separators, and line endings after conversion.
Keep the source until the converted output has been reviewed.

Good next steps

These links move the current task into a more complete workflow.

Real-world use cases

Move a README into a Sphinx doc tree
Your project README is Markdown, but the docs site is built with Sphinx and expects .rst. Paste the README here, get RST with the headings underlined, the code fences turned into code-block directives and the links rewritten as `text <url>`_, then drop the result into docs/intro.rst. No hand-editing every backtick and every link by hand.
Port a GitHub wiki page to Read the Docs
A team wiki page written in Markdown needs to live on Read the Docs, which renders RST. Convert the page in one paste, keep the bullet lists and block quotes intact, and the image at the top becomes a proper .. image:: directive instead of a broken ![]() that RST would render as literal text.
Draft docs in Markdown, ship them as RST
You think faster in Markdown — it is what your editor previews and what your notes are in. Write the page in Markdown, paste it here, and commit the RST output to the Sphinx repo. You keep the authoring speed of Markdown and the toolchain keeps the RST it expects.
Fix code spans that broke after a paste
Someone pasted Markdown straight into a .rst file and every `code` span lost its meaning because RST needs double backticks. Run the original Markdown through here and the inline code comes out as ``code``, so the literal monospaced rendering is restored across the whole page.

Common pitfalls

Making the heading underline too short. RST requires the underline row to be at least as wide as the title text, or Sphinx throws a warning and may drop the heading. This tool sizes the underline to match the title automatically, so 'Setup' always gets exactly five equals signs.
Leaving inline code as a single backtick. A single backtick in RST is an interpreted-text role, not literal code, so `value` pasted from Markdown silently changes meaning. Always use the double-backtick ``value`` form the converter produces.
Keeping Markdown link syntax. RST does not understand [text](url); it needs `text <url>`_ with angle brackets and a trailing underscore. Pasting the Markdown form leaves the link as visible literal text on the rendered page.

Privacy

The whole conversion — heading underlines, code-block directives, link rewriting, every regex pass — is plain JavaScript that runs inside your browser tab. Your Markdown is never uploaded and there is no logging of what you paste. The one caveat: the shareable URL encodes your input in the query string, so a share link pasted into chat records that text in the recipient server's access log. For internal docs, use the copy button and paste the RST directly rather than sharing the URL.

FAQ

Tool combos

Folks in your role tend to reach for these alongside this tool.

Developer

Browse all tools for this role

Markdown to reStructuredText Converter

What this tool does

Tool details

How to use

1. Input

2. Process

3. Copy / Download

How Markdown to reStructuredText fits into your work

Conversion jobs

Conversion checks

Good next steps

Real-world use cases

Move a README into a Sphinx doc tree

Port a GitHub wiki page to Read the Docs

Draft docs in Markdown, ship them as RST

Fix code spans that broke after a paste

Common pitfalls

Privacy

FAQ

Markdown to HTML

Markdown to Jira

HTML to Markdown

Markdown to Plain Text

Angle Converter

Base64 Encoder & Decoder

Base64 to File Converter

BBCode to HTML Converter

Chinese Numeric Converter

Chinese Pinyin Converter

Chinese Zodiac Sign Checker (Sheng Xiao)

Cooking Measurement Converter