{"id":7388,"library":"m2r2","title":"m2r2: Markdown and reStructuredText Converter","description":"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.","status":"active","version":"0.3.4","language":"en","source_language":"en","source_url":"https://github.com/crossnox/m2r2","tags":["markdown","reStructuredText","rst","sphinx","documentation","converter","docutils"],"install":[{"cmd":"pip install m2r2","lang":"bash","label":"Install m2r2"}],"dependencies":[{"reason":"Core Markdown parser","package":"mistune==0.8.4","optional":false},{"reason":"ReStructuredText processing, required for conversion and Sphinx integration","package":"docutils>=0.19","optional":false}],"imports":[{"note":"m2r is the unmaintained predecessor; m2r2 is the active fork.","wrong":"import m2r","symbol":"convert","correct":"from m2r2 import convert"},{"note":"Used for converting Markdown files directly.","symbol":"parse_from_file","correct":"from m2r2 import parse_from_file"}],"quickstart":{"code":"from m2r2 import convert\nimport os\n\n# Programmatic conversion of a Markdown string\nmarkdown_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\"\"\"\nrst_output = convert(markdown_text)\nprint(\"--- Converted RST ---\")\nprint(rst_output)\n\n# Command-line usage (assuming 'my_document.md' exists)\n# You can also run 'm2r2 my_document.md' from your terminal\n# It will create 'my_document.rst'\n\n# For Sphinx integration, add 'm2r2' to extensions in conf.py:\n# extensions = [\n#     'sphinx.ext.autodoc',\n#     'm2r2',\n# ]\n# Then Sphinx will process .md files.","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or higher, or downgrade m2r2 to a compatible version (e.g., <0.3.3).","message":"Version 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.","severity":"breaking","affected_versions":"0.3.3+"},{"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'.","message":"M2R2 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.","severity":"gotcha","affected_versions":"All versions of original `m2r`, especially with Sphinx 3+ or Docutils >=0.19"},{"fix":"Add 'sphinxcontrib.mermaid' to your `conf.py` extensions list if you want to use Mermaid diagrams in your Markdown files via `m2r2`.","message":"When 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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Uninstall `m2r` and install `m2r2`: `pip uninstall m2r && pip install m2r2`. Ensure your Sphinx `conf.py` uses `'m2r2'` in `extensions`.","cause":"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.","error":"ImportError: cannot import name 'ErrorString' from 'docutils.core'"},{"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'`.","cause":"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.","error":"WARNING: could not import extension m2r (exception: cannot import name 'ErrorString' from 'docutils.core')"}]}