M2R converts a markdown file including reStructuredText (rst) markups to a valid rst format.
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.
mdincludedirective to include markdown from md or rst files
Python 2.7 or Python 3.4+ is required.
pip install m2r
python3 -m pip install m2r
m2r command converts markdown file to rst format.
m2r your_document.md [your_document2.md ...]
Then you will find
your_document.rst in the same directory.
m2r.convert function and call it with markdown text.
Then it will return converted text.
from m2r import convert rst = convert('# Title\n\nSentence.') print(rst) # Title # ===== # # Sentence.
parse_from_file function to load markdown file and obtain converted
from m2r 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 m2r import parse_from_file readme = parse_from_file(readme_file) except ImportError: # m2r 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 = [ ..., 'm2r', ] # source_suffix = '.rst' source_suffix = ['.rst', '.md']
Write index.md and run
m2r extension is enabled on sphinx and
.md file is loaded, m2r
converts to rst and pass to sphinx, not making new
.. 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.
If you find any bug or unexpected behaviour, please report it to Issues.
Demo editor of m2r is available. If you are interested in m2r, please try it.
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!