M2R(1)

NAME
m2r - M2R Documentation PyPIPyPI versionBuild Statuscodecov

----

M2R converts a markdown file including reST markups to a valid reST 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 reST markups and sphinx extensions. For example, reST'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 reST 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 reST files

INSTALLATION

Python 2.7 or Python 3.3+ is required.

pip install m2r

USAGE

  Command Line

m2r command converts markdown file to reST format.

m2r your_document.md [your_document2.md ...]

Then you will find your_document.rst in the same directory.

  Programmatic Use

Instantiate M2R class and call with markdown text. Then it will return converted text.

from m2r import M2R
m2r = M2R()
rest = m2r('# Title\n\nSentence.')
print(rest)
# 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 reST 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 reST 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 reST's directives, markdown is not available. Please write in reST.

•   Column alignment of tables is not supported. (reST does not support this feature)

•   Heading with overline-and-underline is not supported.

•   Heading with underline is OK

    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.

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

MIT

CONTENTS

  Example

This page is written in mixed markdown and reST. Source code is here.

  Basic Markups (inline)

A strong, emphasis, , code with single-backtick, code with two-backticks, , reST's code role, and delete.

  Link

Auto link to http://example.com/.

Link to example.com in markdown.

Link to example.com in reST.

Link to example in reST_ref.

  Basic Markups (block)

This is a simple sentence.
sentence with
newlines
(reST)

Sentence with hard-wrap (markdown, trailing two spaces) block quote second line nested quote

----

Block quote after raw-html directive

  List

  Unordered list

•   unordered list new line

•   next item

•   nested list with new line

•   nested list item 2

•   original depth

1.  ordered list item

2.  second with new line

•   original depth again

  Ordered list

1.  ordered list in new line

2.  second item

•   nested unordered list

•   second item with new line

3.  original depth

1.  nested ordered list with new line

2.  again

4.  original depth again

  Code Block

Simple, indented code block

pip install sphinx

Code block with triple backticks and language.

def a(n: int) -> None:
    for i in range(n):
        print(i)

Triple-tildes (~~~) are also available.

def a(n: int) -> None:
    for i in range(n):
        print(i)

Here is reST style code block.

if True:
    print('\n')

  Extensions

  Table (Markdown-Style)

(cell-alignment is not supported currently)
Table Header 1 | Table Header 2 | Table Header 3
normal | italic | bold
code |  |

  Math

This is E = mc^2 inline math.

The below is math-block (markdown-style).

The below is reST-style math-block.

  Footnote

Footnote[2] and footnote[3] with markdown.

Footnote with reST[1].

[1] reST footnote

[2] footnote 1

[3] footnote key

  Change Log

  Version 0.2

(next version)

  Version 0.1.5 (2016-06-21)

•   Support multiple backticks in inline code, like:

  Version 0.1.4 (2016-06-08)

•   Support indented directives/reST-comments

•   Support role-name after backticks (`text`:role: style)

  Version 0.1.3 (2016-06-02)

•   Remove extra escaped-spaces ('')

•   before and after normal spaces

•   at the beginning of lines

•   before dots

  Version 0.1.2 (2016-06-01)

•   Add reST's :: marker support

•   Add options to disable emphasis by underscore (_ or __)

  Version 0.1.1 (2016-05-30)

•   Fix Bug: when code or link is placed at the end of line, spaces to the next word is disappeared

  Version 0.1 (2016-05-30)

First public release.

•   genindex

•   modindex

•   search

AUTHOR
Hiroyuki Takagi

COPYRIGHT
2016, Hiroyuki Takagi