m2r2
Markdown and reStructuredText in a single file.
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.7 or later.
- 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 · maintenance · safety
MIT (permissive) — MIT license permits commercial and private use with minimal restrictions; you must include the license text in distributions but face no copyleft obligations.
last release 2025-05-01 (470 days) · last repo commit 2026-02-17 · 114 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 281,198 downloads/mo, #8,103 on PyPI
Alternatives
Verify before relying
pip install m2r2
from m2r2 import convert
rst = convert('# Title\n\nSentence.')
print(rst)- 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.
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 on this page. Verify before relying on it.
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
m2r2 on PyPI
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.
Requires Python 3.7 or later.
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)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 the current Python release >=3.7 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 2 packagesmistunedocutils |
| Maintenance | Actively maintained 470 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 281,198 / month, #8,103 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 4 - BetaFramework :: Sphinx :: ExtensionIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseNatural Language :: EnglishProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.7Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9Topic :: Text Processing |
Evidence: m2r2-0.3.4-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “markdown to rst converter”
- m2r2Converts markdown files with embedded reStructuredText markup to…
- docstring-to-markdownConverts Python docstrings from reStructuredText and Google format to…
- sphinx-markdown-builderA Sphinx extension that generates Markdown output from…
Give your agent the search over MCP, or paste the wish link into any chat.
More Text Processing packages
A drop-in replacement for Python's standard `re` module that adds advanced regex features like nested sets, fuzzy matching, lookaround in conditionals, and full Unicode case-folding while maintaining backward compatibility.
pyparsing provides a library for building text parsers directly in Python code using composable grammar classes, handling quoted strings, whitespace variation, and embedded comments without regex or lex/yacc.
Install it if you need to parse text or define grammars programmatically.
fonttools manipulates font files in multiple formats (TrueType, OpenType, AFM, Type 1, Mac-specific) and includes TTX, a tool to convert fonts to and from XML text format.
Install it if you need to read, write, or manipulate fonts programmatically or via the TTX command-line tool.
Docutils converts plaintext documentation in reStructuredText format into multiple output formats including HTML, XML, and LaTeX using a modular processing system.
RapidFuzz provides fast fuzzy string matching using Levenshtein Distance and related metrics, implemented mostly in C++ with Python bindings for rapid similarity scoring and approximate string matching.
Install it if you need fuzzy string matching; it's a solid replacement for FuzzyWuzzy with better licensing and performance.
tinycss2 parses CSS strings into token and block objects, and generates CSS strings from those objects, following the CSS Syntax Level 3 specification without enforcing specific properties or values.
Install it if your project requires CSS tokenization or syntax manipulation.
See also docstring-to-markdown · setuptools-markdown · sphinx_mdinclude · sphinx-markdown-tables · rich-rst · recommonmark · sphinx-markdown-builder · rst2pdf · sphinxcontrib-confluencebuilder · esbonio