---
id: m2r2
version: "0.3.4"
license: MIT
license_treatment: permissive
maintenance: active
---

# m2r2 — Markdown and reStructuredText in a single file.

License: permissive · Maintenance: active · Downloads: 281.2K/mo

## What it is and what it does

M2R2 is a markdown-to-reStructuredText converter designed to let you write Sphinx documentation in markdown while preserving reStructuredText markup and Sphinx extensions that other converters drop. It extends the markdown parser mistune to handle inline and block-level rst constructs like directives, roles, and reference links, which would otherwise be lost in conversion. The package works both as a command-line tool and as a Sphinx extension that transparently converts .md files during documentation builds.

The core problem it solves is that standard markdown converters (pandoc, recommonmark) don't support many rst features—particularly reference links and Sphinx-specific directives—making them unsuitable for projects that rely on those capabilities. M2R2 is a maintained fork of the original m2r project, addressing issues that broke Sphinx 3 compatibility and keeping pace with modern Python versions (3.7–3.13).

Use it for:

- Write Sphinx documentation in markdown while keeping rst directives and cross-references intact for the build.
- Convert existing markdown README files to rst format for PyPI publication without losing formatting.
- Include markdown files directly in Sphinx projects using the mdinclude directive alongside rst files.
- Automate markdown-to-rst conversion in CI/CD pipelines for documentation generation.
- Render mermaid diagram blocks in Sphinx when sphinxcontrib.mermaid is available.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts markdown files with embedded reStructuredText markup to valid reStructuredText format, supporting Sphinx integration for building documentation directly from markdown sources.

Yes. M2R2 is actively maintained, has no known vulnerabilities, low install friction, and solves a real problem for projects that need markdown authoring with full reStructuredText and Sphinx feature support. Install it if you want to write Sphinx docs in markdown without losing rst markup or Sphinx extensions.

## Install

pip install m2r2
uv add m2r2
poetry add m2r2

## Installing m2r2

Before you install: Low install friction with only two runtime dependencies (mistune and docutils). Actively maintained with recent commits; last release was 470 days ago and repository remains active with 114 stars.

License in practice: MIT license permits commercial and private use with minimal restrictions; you must include the license text in distributions but face no copyleft obligations.

Quickstart:

pip install m2r2

from m2r2 import convert
rst = convert('# Title\n\nSentence.')
print(rst)

Requires Python 3.7 or later.

Verify before relying:

- Whether the package handles all reStructuredText directives and roles correctly in mixed markdown/rst documents.
- Performance characteristics when processing large markdown files or many files in batch.
- Compatibility with recent Sphinx versions beyond those in the classifier list.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 281.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

markdown to rst converter, sphinx markdown support, reStructuredText from markdown, markdown rst hybrid, sphinx extension markdown, convert md to rst, markdown documentation sphinx, sphinx-extension, markdown-conversion, documentation-tooling

[View on SkillFed](https://skillfed.io/packages/m2r2) · [View on PyPI](https://pypi.org/project/m2r2/)