RST to Markdown Converter for MkDocs Migration

Convert reStructuredText to Markdown for MkDocs, Jekyll, Hugo. Migrate Sphinx docs with immediate conversion. Preserves code, links, tables.

Note: First conversion initializes Pandoc WebAssembly (~55MB). Subsequent conversions are instant.

Drop RST file here or click to browse

Accepts .rst, .txt files

reStructuredText Input

Markdown Output (GFM)

GitHub-Flavored Markdown

RST to Markdown Conversion Guide

reStructuredText	Markdown (GFM)	Notes
`Heading =======`	`# Heading`	H1 title
`Subheading ----------`	`## Subheading`	H2 subtitle
`bold`	`bold`	Same syntax in both
`italic`	`italic`	Same syntax in both
``code``	`code`	Markdown uses single backticks
`.. code-block:: python code`	```python code ```	Fenced code blocks in Markdown
`link <url>`_	`[link](url)`	Markdown inline link
`.. image:: img.png :alt: alt`	`![alt](img.png)`	Markdown image syntax
`* Item`	`- Item`	Markdown uses hyphens/asterisks
`1. Item`	`1. Item`	Numbered lists similar

Sphinx to MkDocs Migration Workflow

After converting RST to Markdown, set up MkDocs:

Install MkDocs: pip install mkdocs mkdocs-material
Initialize project: mkdocs new my-project
Add converted Markdown files to docs/ directory
Configure mkdocs.yml: Set site name, theme, navigation structure
Preview locally: mkdocs serve (live reload on http://127.0.0.1:8000)
Build static site: mkdocs build (outputs to site/ directory)
Deploy: mkdocs gh-deploy for GitHub Pages, or integrate with Netlify/Vercel

Sample mkdocs.yml configuration:

site_name: My Documentation
theme:
  name: material
  palette:
    scheme: default
    primary: indigo
nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api/
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: true

Copied to clipboard

Markdown to MediaWiki - GitHub to Wikipe…

Tiki Wiki to Markdown - Open Source Wiki…

BBCode to HTML Converter - Convert Forum…

txt2tags to Markdown - T2T Format Conver…

Man Page to HTML Converter - Unix Docume…

View all Markup converters →

Frequently Asked Questions

Markdown is more widely supported across platforms like GitHub, GitLab, MkDocs, Jekyll, and Hugo. Converting RST to Markdown allows you to migrate Python documentation from Sphinx/ReadTheDocs to modern static site generators, making documentation more accessible and easier to maintain.

RST (reStructuredText) is more feature-rich and extensible, designed for technical documentation with Sphinx. Markdown is simpler, more universal, and better supported by version control platforms. Markdown has better tooling for modern documentation workflows and is easier for contributors to learn.

Yes. This converter helps migrate Sphinx/RST projects to MkDocs/Markdown. MkDocs offers a modern, fast documentation experience with excellent theming (Material for MkDocs), live reload during development, and better integration with CI/CD pipelines. After conversion, organize files in docs/ directory and configure mkdocs.yml.

Common RST directives are converted to equivalent Markdown syntax. Code-block directives become fenced code blocks (```), image directives become image syntax (![alt](src)), notes/warnings become blockquotes or admonitions (if using Material for MkDocs), and links are converted to inline format.

Sphinx-specific directives like autodoc, toctree, and cross-references don't have direct Markdown equivalents. These are preserved as plain text or converted to closest approximations. For API documentation, consider using MkDocs plugins like mkdocstrings for automatic API documentation from Python docstrings.

GitHub-flavored Markdown is a Markdown variant used by GitHub, GitLab, and many modern tools. It adds features like fenced code blocks with syntax highlighting, tables, task lists, strikethrough, and autolinks. This converter outputs GFM for maximum compatibility with modern platforms.

RST code-block directives (.. code-block:: python) are converted to GitHub-flavored fenced code blocks (```python). Language identifiers are preserved for syntax highlighting. Inline literals (``code``) become single-backtick inline code (`code`).

Yes. RST tables (grid tables and simple tables) are converted to Markdown pipe tables. Complex RST tables with merged cells or intricate formatting may require manual adjustment after conversion, as Markdown tables have simpler structure.

Absolutely. All conversion happens locally in your browser using Pandoc WebAssembly. Your RST documentation files are never uploaded to any server, no data is transmitted externally, and no tracking occurs. Completely private, secure, and works offline after initial load.

MkDocs is simpler to set up, has faster build times, offers better live-reload development experience, uses more familiar Markdown syntax, has excellent themes (Material for MkDocs), better mobile responsiveness, and integrates seamlessly with GitHub/GitLab workflows. It's ideal for project documentation that prioritizes accessibility and modern UX.

RST to Markdown Conversion Guide

Sphinx to MkDocs Migration Workflow

Related Tools