⌘ K
GFM → reST · underline headings · .. code-block:: · `text <url>`_

Convert Markdown to reStructuredText

Reformat Markdown into reST for Sphinx, Python docs, and ReadTheDocs — underline-style headings, code-block directives, and roles for inline code and links.

Markdown → reST
Input
146 B
15 lines
Output
178 B
18 lines
Status
ready
live
Ratio
1.22×
out/in
input · markdown
output · reST
Project
=======

Install
-------

``pip install foo``

.. code-block:: python

   import foo
   foo.run()


**Bold** and *italic* with `docs <https://example.com>`_.

* one
* two
Quick Start

How to convert Markdown to reST

reST uses underline-style headings, .. code-block:: directives, and back-tick roles for links. The converter walks each line and maps every common Markdown form to a valid reST equivalent.

  1. 01

    Paste Markdown

    From your README or Sphinx draft.

    Parsing runs through marked with GFM extensions enabled — tables, task lists, strikethrough, and fenced code blocks all match GitHub’s rendering.

    inputGFMmarkedCommonMarklive
    input · markdownmd · GFM
    # Title
    loaded · GFMGFM · ready
  2. 02

    Map headings

    # Title becomes underlined with ===, ## with ---, etc.

    Soft-break behaviour is configurable: by default a single newline becomes a space (CommonMark), toggle on for chat-style <br> insertion.

    headingsoft-breaksoptionsconfiglive
    fix · optionsreST · live
    Title
=====
    options applied · livelive
  3. 03

    Map roles + directives

    `code` → ``code``; [t](u) → `t <u>`_; ``` becomes .. code-block::.

    The preview is scoped under a .mde class so its CSS doesn’t bleed into the rest of the page. Output HTML is whitespace-controlled for clean diffs.

    mappreviewscoped CSSrenderstable
    out · renderedreST · ready
    .. code-block:: py
    rendered · liverendered
  4. 04

    Drop into Sphinx

    Save as .rst and feed to sphinx-build.

    Export covers both raw Markdown and rendered HTML; downloads stream as text/markdown or text/html via Blob + object URL.

    exportclipboard.md.htmlblob
    OK · exported.rst · done
    shipped
    shipped · ready to shipsuccess
Pro tips

Author Markdown that renders everywhere

GFM is the safe default

GitHub-Flavored Markdown is the de-facto baseline (tables, task lists, strikethrough). CommonMark is stricter but ubiquitous as a fallback.

Soft-break behaviour varies

A single newline is a space in CommonMark, a <br> in GFM. Toggle soft breaks when source matters.

Escape inside code fences

Backticks inside fenced blocks need a longer fence — three becomes four. Use ~~~ if your content has many backticks.

Anchors are slugified

GitHub lowercases, strips punctuation, and joins with hyphens. Duplicate headings get -1, -2 suffixes.

Tables need a header row

The dash row sets alignment (:---, :-:, ---:). Use Table Aligner for diff-friendly columns.

Front matter is YAML

Triple-dash blocks at the top of files are parsed by static-site generators. Use the Front-Matter Validator to catch syntax errors.

Related toolsAsciiDocHTMLLaTeXConfluenceJiraEditor
Use Cases

When to convert to reST

Sphinx, ReadTheDocs, and Python ecosystem docs.

Sphinx projects

Mirror Markdown READMEs into the docs/ source tree. Render path uses marked with GFM extensions enabled (tables, task lists, strikethrough, autolinks), so what you preview matches what GitHub publishes bit-for-bit. Soft-break behaviour is configurable for chat-style vs prose Markdown.

GFM-compliant

ReadTheDocs

Author drafts in Markdown, publish as reST. Pairs cleanly with the Markdown Cheatsheet for syntax you can't quite remember — callout blocks, footnotes, definition lists. Output stays diff-friendly so style-only changes don't drown out real edits in PRs.

GitHub-perfect

PyPI long_description

Bridge GitHub Markdown to PyPI reST renderer. Cross-platform safe: anchors, code fences, and tables behave identically on GitHub, GitLab, Bitbucket, and Gitea. Heading-anchor slugs follow GitHub's lowercase-and-hyphenate rules so deep links survive a docs migration.

diff-friendly

Module docstrings

Convert MD examples for inclusion in Python docstrings. No server roundtrip — perfect for proprietary content you can't paste into a public tool. The full marked + GFM bundle ships with the page, so it works offline once loaded.

render-stable

Migration

Bulk-convert a Markdown wiki to a Sphinx site. Front matter (YAML / TOML / JSON) passes through unchanged so static-site pipelines (Jekyll, Hugo, Astro, Eleventy) read it correctly. Pair with the Front-Matter Validator to catch syntax errors before deploy.

cross-platform

Cross-publishing

Maintain one Markdown source, ship reST + HTML. Output is reproducible: identical input always produces identical Markdown, so doc-generation scripts can rely on it for snapshot tests and embedded into release workflows.

SEO-friendly
FAQ

Frequently asked questions

No — Markdown table syntax is left as-is. Sphinx accepts grid tables; convert by hand or use a Markdown extension.
Six levels, mapped to =, -, ~, ^, ", '. These are common Sphinx defaults but the convention is project-specific.
Backtick code becomes ``double-backtick``; images become .. image:: directives with an :alt: option.
Markdown footnotes are left unchanged — reST footnotes use a different syntax; review by hand.
No. Conversion runs locally in your browser.
Suggest a tool

Something missing?

Tell us what you need. We ship the top requests every two weeks.

Sent straight to the maintainers · no account needed
47 in queue·8 shipped this month
Request queued. Thanks!