Package: m2r2
M2R2M2R2 converts a markdown file including reStructuredText (rst) markups to a valid
rst format.M2R: the originalM2R2 is a fork ofm2rwhich 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 usingsphinx3. Everym2rconfig 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 withm2r2.Why another converter?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 likesee `ref`_(this is very convenient in
long document in which same link appears multiple times) will be converted to
a code block in HTML likesee <code>ref</code>_, which is not expected.FeaturesBasic markdown and some extensions (see below)inline/block-level raw htmlfenced-code blocktablesfootnotes ([^1])Inline- and Block-level rst markupssingle- and multi-line directives (.. directive::)inline-roles (:code:`print(1)` ...)ref-link (see `ref`_)footnotes ([#fn]_)math extension inspired byrecommonmarkSphinx extensionadd markdown support for sphinxmdincludedirective to include markdown from md or rst filesoption to parse relative links into ref and doc directives (m2r_parse_relative_links)option to rendermermaidblocks as graphs withsphinxcontrib.mermaid(m2r_use_mermaid, default: auto)auto means that m2r2 will check ifsphinxcontrib.mermaidhas been added to the extensions listPure python implementationpandoc is not requiredInstallationPython 2.7 or Python 3.4+ is required.pip install m2r2Orpython3 -m pip install m2r2or usingcondaconda install -c conda-forge m2r2UsageCommand Linem2r2command converts markdown file to rst format.m2r2 your_document.md [your_document2.md ...]Then you will findyour_document.rstin the same directory.Programmatic UseImportm2r2.convertfunction and call it with markdown text.
Then it will return converted text.fromm2r2importconvertrst=convert('# Title\n\nSentence.')print(rst)# Title# =====## Sentence.Or, useparse_from_filefunction to load markdown file and obtain converted
text.fromm2r2importparse_from_fileoutput=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:fromm2r2importparse_from_filereadme=parse_from_file(readme_file)exceptImportError:# m2r2 may not be installed in user environmentwithopen(readme_file)asf:readme=f.read()setup(...,long_description=readme,...,)Sphinx IntegrationIn your conf.py, add the following lines.extensions=[...,'m2r2',]# source_suffix = '.rst'source_suffix=['.rst','.md']Write index.md and runmake html.Whenm2r2extension is enabled on sphinx and.mdfile is loaded, m2r2
converts to rst and pass to sphinx, not making new.rstfile.mdinclude directiveLike.. include:: filedirective,.. mdinclude:: filedirective inserts
markdown file at the line.Note: do not use.. include:: filedirective to include markdown file even if
in the markdown file, please use.. mdinclude:: fileinstead.RestrictionsIn the rst's directives, markdown is not available. Please write in rst.Column alignment of tables is not supported. (rst does not support this feature)Heading with overline-and-underline is not supported.Heading with underline is OKRst heading marks are currently hard-coded and unchangeable.H1:=, H2:-, H3:^, H4:~, H5:", H6:#If you find any bug or unexpected behaviour, please report it toIssues.ExampleSeeexample documentandits
source code.Note from the original author:I'm using m2r for writing user guide ofWDOM.
So you can see it as another example. ItsHTML is
here, andits
source code is here.Demo editorNote: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/m2rdemoDev installPlease install thedevdependencies andpre-commithooks with:pipinstall-rrequirements-dev.txt
pre-commitinstallAcknowledgementm2r is written as an extension ofmistune, which is highly extensible
pure-python markdown parser.
Without the mistune, I couldn't write this. Thank you!LicenceMIT