m2r2

library0.3.4pypypi✓ verified 85d ago

M2R2 is a Python library designed to convert Markdown files, including embedded reStructuredText (RST) markups, into a valid RST format. It is a actively maintained fork of the original `m2r` library, specifically addressing compatibility issues with Sphinx 3+ and newer Python versions. M2R2 also functions as a Sphinx extension, enabling developers to write documentation in Markdown directly within Sphinx projects. The current version is 0.3.4, with a focused release cadence primarily for maintenance and compatibility updates.

serialization web-framework

pip install m2r2

github ↗package ↗

INSTALL

IMPORT

SIG · M2R2

m2r2

serializationpythonv0.3.4

Install

1.9s avg

Import

460ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.498s · 22.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.9s · import 0.422s · 23MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

convert

✓ from m2r2 import convert

✗ import m2r

m2r is the unmaintained predecessor; m2r2 is the active fork.

parse_from_file

✓ from m2r2 import parse_from_file

Used for converting Markdown files directly.

This quickstart demonstrates how to programmatically convert a Markdown string to reStructuredText using the `convert` function. It also highlights the command-line utility and how to integrate `m2r2` as a Sphinx extension by adding 'm2r2' to your `conf.py` extensions list, allowing Sphinx to process `.md` files directly.

from m2r2 import convert import os # Programmatic conversion of a Markdown string markdown_text = """# My Document\n\nThis is **Markdown** with `inline code` and also `reST :role:` content.\n\n.. admonition:: Note\n This is reStructuredText inside Markdown.\n""" rst_output = convert(markdown_text) print("--- Converted RST ---") print(rst_output) # Command-line usage (assuming 'my_document.md' exists) # You can also run 'm2r2 my_document.md' from your terminal # It will create 'my_document.rst' # For Sphinx integration, add 'm2r2' to extensions in conf.py: # extensions = [ # 'sphinx.ext.autodoc', # 'm2r2', # ] # Then Sphinx will process .md files.

Debug

Known issues

breakingVersion 0.3.3 dropped support for Python versions prior to 3.7. Ensure your environment uses Python 3.7 or newer to avoid compatibility issues.

fix

Upgrade your Python environment to 3.7 or higher, or downgrade m2r2 to a compatible version (e.g., <0.3.3).

affects: 0.3.3+

gotchaM2R2 is a fork of the unmaintained `m2r` library. Using `m2r` (the original) with newer Sphinx or Docutils versions can lead to `ImportError` or other compatibility issues. Always prefer `m2r2` for modern Python and Sphinx projects.

fix

Ensure you `pip install m2r2` and replace any `import m2r` with `from m2r2 import convert` or similar, and update Sphinx extensions from 'm2r' to 'm2r2'.

affects: All versions of original `m2r`, especially with Sphinx 3+ or Docutils >=0.19

gotchaWhen using `m2r2` as a Sphinx extension, ensure `sphinxcontrib.mermaid` is also in your `extensions` list if you intend to render Mermaid diagrams using the `.. mermaid::` directive, especially if `m2r_use_mermaid` is set to 'auto' (the default).

fix

Add 'sphinxcontrib.mermaid' to your `conf.py` extensions list if you want to use Mermaid diagrams in your Markdown files via `m2r2`.

affects: All versions

Errors

Common errors & fixes

ImportError: cannot import name 'ErrorString' from 'docutils.core'

This error typically occurs when using the older `m2r` library with a newer version of `docutils` (e.g., Docutils 0.19+), which removed `ErrorString` from `docutils.core`. M2R2 was updated to address this incompatibility.

fix

Uninstall `m2r` and install `m2r2`: `pip uninstall m2r && pip install m2r2`. Ensure your Sphinx `conf.py` uses `'m2r2'` in `extensions`.

WARNING: could not import extension m2r (exception: cannot import name 'ErrorString' from 'docutils.core')

Sphinx failed to load the `m2r` extension due to a breaking change in `docutils` where `ErrorString` was removed. This specifically points to using the outdated `m2r` with an incompatible `docutils` version.

fix

Upgrade to `m2r2` by running `pip uninstall m2r && pip install m2r2`. Also, update your Sphinx `conf.py` to use `extensions = ['m2r2']` instead of `'m2r'`.

Upgrade

Version history

0.3.4latest on PyPI · released May 1, 2025

Audit

Dependencies

mistune==0.8.4requiredCore Markdown parser

docutils>=0.19requiredReStructuredText processing, required for conversion and Sphinx integration

Agent activity

19 hits · last 30 days

node

Resources

githubhttps://github.com/crossnox/m2r2 ↗

packagehttps://pypi.org/project/m2r2/ ↗