m2r

m2r is a Python-based converter and Sphinx extension that translates Markdown files into reStructuredText so they can be processed by Sphinx, a documentation generator that natively uses reStructuredText. It was created to bridge the gap between Markdown authorship and Sphinx’s rst-based workflow. The tool provides a command-line interface and a small Python API, enabling users to convert .md files to .rst. It can be installed via pip install m2r.

In typical usage, you add 'm2r' to the Sphinx extensions list and place Markdown docs in the source tree; m2r handles common Markdown syntax, including headings, emphasis, lists, code blocks, links, images, and tables, converting them to equivalent reStructuredText constructs. The result can then be included in Sphinx builds alongside standard .rst documents.

Limitations include that complex or nonstandard Markdown features may not translate perfectly; the project may be less active or superseded by newer approaches such as MyST-Parser, which supports Markdown more natively within Sphinx. Some projects use m2r2, a fork with updated Python compatibility and extended features. The m2r ecosystem thus reflects broader trends toward Markdown-first documentation in Python communities.

See also: Sphinx, reStructuredText, Markdown, MyST.