M2R
M2R converts a markdown file including reStructuredText (rst) markups to a valid rst format.
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 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.
Features
Basic markdown and some extensions (see below)
inline/block-level raw html
fenced-code block
tables
footnotes ([^1])
Inline- and Block-level rst markups
single- and multi-line directives (.. directive::)
inline-roles (:code:`print(1)` ...)
ref-link (see `ref`_)
footnotes ([#fn]_)
math extension inspired by recommonmark
Sphinx extension
add markdown support for sphinx
mdinclude directive to include markdown from md or rst files
option to parse relative links into ref and doc directives (m2r_parse_relative_links)
Pure python implementation
pandoc is not required
Installation
Python 2.7 or Python 3.4+ is required.
pip install m2rOr,
python3 -m pip install m2rUsage
Command Line
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.
Programmatic Use
Import 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.Or, use parse_from_file function to load markdown file and obtain converted text.
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,
...,
)Sphinx Integration
In your conf.py, add the following lines.
extensions = [
...,
'm2r',
]
# source_suffix = '.rst'
source_suffix = ['.rst', '.md']Write index.md and run make html.
When m2r extension is enabled on sphinx and .md file is loaded, m2r converts to rst and pass to sphinx, not making new .rst file.
mdinclude directive
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.
Restrictions
In 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 OK
Rst 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 to Issues.
Example
See example document and its source code.
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.
Demo editor
Demo editor of m2r is available. If you are interested in m2r, please try it.
Acknowledgement
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!
Licence
1 maintainer
Metadata
1 maintainer
Release files for m2r 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| m2r-0.2.1.tar.gz | 16.1 kB | Details |
Release files / m2r-0.2.1.tar.gz
| Download URL | m2r-0.2.1.tar.gz |
|---|---|
| Size | 16.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bf90bad66cda1164b17e5ba4a037806d2443f2a4d5ddc9f6a5554a0322aaed99
|
|
BLAKE2b-256 checksum How to use checksums |
39e79fae11a45f5e1a3a21d8a98d02948e597c4afd7848a0dbe1a1ebd235f13e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Python-urllib/3.7
|
