M2R2 converts a markdown file including reStructuredText (rst) markups to a valid rst format.
M2R2 is a fork of m2r which hasn't been updated for a long time
and there's been no response from the author about a PR fixing a serious issue that broke several
pipelines using sphinx3
. Every m2r
config should work out of the box. I've changed some of the tooling for what I'm mostly using now. Below goes
the original readme, changing only what's needed to work with m2r2
.
I wanted to write sphinx document in markdown, since it's widely used now and
easy to write code blocks and lists. However, converters using pandoc or
recommonmark do not support many rst markups and sphinx extensions. For
example, rst's reference link like see `ref`_
(this is very convenient in
long document in which same link appears multiple times) will be converted to
a code block in HTML like see <code>ref</code>_
, which is not expected.
[^1]
).. directive::
):code:`print(1)` ...
)see `ref`_
)[#fn]_
)mdinclude
directive to include markdown from md or rst filesm2r_parse_relative_links
)mermaid
blocks as graphs with sphinxcontrib.mermaid (m2r_use_mermaid
, default: auto)
sphinxcontrib.mermaid
has been added to the extensions listPython 2.7 or Python 3.4+ is required.
pip install m2r2
Or
python3 -m pip install m2r2
or using conda
conda install -c conda-forge m2r2
m2r2
command converts markdown file to rst format.
m2r2 your_document.md [your_document2.md ...]
Then you will find your_document.rst
in the same directory.
Import m2r2.convert
function and call it with markdown text.
Then it will return converted text.
from m2r2 import convert
rst = convert('# Title\n\nSentence.')
print(rst)
# Title
# =====
#
# Sentence.
Or, use parse_from_file
function to load markdown file and obtain converted
text.
from m2r2 import parse_from_file
output = parse_from_file('markdown_file.md')
This is an example of setup.py to write README in markdown, and publish it to PyPI as rst format.
readme_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'README.md')
try:
from m2r2 import parse_from_file
readme = parse_from_file(readme_file)
except ImportError:
# m2r2 may not be installed in user environment
with open(readme_file) as f:
readme = f.read()
setup(
...,
long_description=readme,
...,
)
In your conf.py, add the following lines.
extensions = [
...,
'm2r2',
]
# source_suffix = '.rst'
source_suffix = ['.rst', '.md']
Write index.md and run make html
.
When m2r2
extension is enabled on sphinx and .md
file is loaded, m2r2
converts to rst and pass to sphinx, not making new .rst
file.
Like .. include:: file
directive, .. mdinclude:: file
directive inserts
markdown file at the line.
Note: do not use .. include:: file
directive to include markdown file even if
in the markdown file, please use .. mdinclude:: file
instead.
=
, H2: -
, H3: ^
, H4: ~
, H5: "
, H6: #
If you find any bug or unexpected behaviour, please report it to Issues.
See example document and its source code.
Note from the original author: I'm using m2r for writing user guide of WDOM. So you can see it as another example. Its HTML is here, and its source code is here.
Note: This hasn't received any updates.
Demo editor of m2r is available. If you are interested in m2r, please try it.
https://github.com/miyakogi/m2rdemo
Please install the dev
dependencies and pre-commit
hooks with:
pip install -r requirements-dev.txt
pre-commit install
m2r is written as an extension of mistune, which is highly extensible pure-python markdown parser. Without the mistune, I couldn't write this. Thank you!