NO MORE UPDATES
===============
Feel free to fork and update.
----
Old README
M2R
===
.. image:: https://img.shields.io/pypi/v/m2r.svg
:target: https://pypi.python.org/pypi/m2r
:alt: PyPI
.. image:: https://img.shields.io/pypi/pyversions/m2r.svg
:target: https://pypi.python.org/pypi/m2r
:alt: PyPI version
.. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
:target: https://miyakogi.github.io/m2r
:alt: Documentation
.. image:: https://travis-ci.org/miyakogi/m2r.svg?branch=master
:target: https://travis-ci.org/miyakogi/m2r
:alt: Build Status
.. image:: https://codecov.io/gh/miyakogi/m2r/branch/master/graph/badge.svg
:target: https://codecov.io/gh/miyakogi/m2r
:alt: codecov
----
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 <https://recommonmark.readthedocs.io/en/latest/index.html>`_
* 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 3.7+ is required.
.. code-block::
pip install m2r
Or,
.. code-block::
python3 -m pip install m2r
Usage
-----
Command Line
^^^^^^^^^^^^
``m2r`` command converts markdown file to rst format.
.. code-block::
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.
.. code-block:: python
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.
.. code-block:: python
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.
.. code-block:: python
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.
.. code-block:: python
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 <https://github.com/miyakogi/m2r/issues>`_.
Example
-------
See `example document <https://miyakogi.github.io/m2r/example.html>`_ and `its
source code <https://github.com/miyakogi/m2r/blob/master/docs/example.md>`_.
I'm using m2r for writing user guide of `WDOM <https://github.com/miyakogi/wdom>`_.
So you can see it as another example. Its `HTML is
here <http://wdom-py.readthedocs.io/en/latest/guide/index.html>`_\ , and `its
source code is here <https://github.com/miyakogi/wdom/tree/dev/docs/guide>`_.
Demo editor
^^^^^^^^^^^
Demo editor of m2r is available.
If you are interested in m2r, please try it.
`https://github.com/miyakogi/m2rdemo <https://github.com/miyakogi/m2rdemo>`_
Acknowledgement
---------------
m2r is written as an extension of
`mistune <http://mistune.readthedocs.io/en/latest/>`_\ , which is highly extensible
pure-python markdown parser.
Without the mistune, I couldn't write this. Thank you!
Licence
-------
`MIT <https://github.com/miyakogi/m2r/blob/master/LICENSE>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/miyakogi/m2r",
"name": "m2r",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Markdown reStructuredText sphinx-extension",
"author": "Hiroyuki Takagi",
"author_email": "miyako.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/94/65/fd40fbdc608298e760affb95869c3baed237dfe5649d62da1eaa1deca8f3/m2r-0.3.1.tar.gz",
"platform": null,
"description": "\nNO MORE UPDATES\n===============\n\nFeel free to fork and update.\n\n----\n\nOld README\n\nM2R\n===\n\n\n.. image:: https://img.shields.io/pypi/v/m2r.svg\n :target: https://pypi.python.org/pypi/m2r\n :alt: PyPI\n\n\n.. image:: https://img.shields.io/pypi/pyversions/m2r.svg\n :target: https://pypi.python.org/pypi/m2r\n :alt: PyPI version\n\n\n.. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg\n :target: https://miyakogi.github.io/m2r\n :alt: Documentation\n\n\n.. image:: https://travis-ci.org/miyakogi/m2r.svg?branch=master\n :target: https://travis-ci.org/miyakogi/m2r\n :alt: Build Status\n\n\n.. image:: https://codecov.io/gh/miyakogi/m2r/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/miyakogi/m2r\n :alt: codecov\n\n\n----\n\nM2R converts a markdown file including reStructuredText (rst) markups to a valid\nrst format.\n\nWhy another converter?\n----------------------\n\nI wanted to write sphinx document in markdown, since it's widely used now and\neasy to write code blocks and lists. However, converters using pandoc or\nrecommonmark do not support many rst markups and sphinx extensions. For\nexample, rst's reference link like ``see `ref`_`` (this is very convenient in\nlong document in which same link appears multiple times) will be converted to\na code block in HTML like ``see <code>ref</code>_``\\ , which is not expected.\n\nFeatures\n--------\n\n\n* Basic markdown and some extensions (see below)\n\n * inline/block-level raw html\n * fenced-code block\n * tables\n * footnotes (\\ ``[^1]``\\ )\n\n* Inline- and Block-level rst markups\n\n * single- and multi-line directives (\\ ``.. directive::``\\ )\n * inline-roles (\\ ``:code:`print(1)` ...``\\ )\n * ref-link (\\ ``see `ref`_``\\ )\n * footnotes (\\ ``[#fn]_``\\ )\n * math extension inspired by `recommonmark <https://recommonmark.readthedocs.io/en/latest/index.html>`_\n\n* Sphinx extension\n\n * add markdown support for sphinx\n * ``mdinclude`` directive to include markdown from md or rst files\n * option to parse relative links into ref and doc directives (\\ ``m2r_parse_relative_links``\\ )\n\n* Pure python implementation\n\n * pandoc is not required\n\nInstallation\n------------\n\nPython 3.7+ is required.\n\n.. code-block::\n\n pip install m2r\n\nOr,\n\n.. code-block::\n\n python3 -m pip install m2r\n\nUsage\n-----\n\nCommand Line\n^^^^^^^^^^^^\n\n``m2r`` command converts markdown file to rst format.\n\n.. code-block::\n\n m2r your_document.md [your_document2.md ...]\n\nThen you will find ``your_document.rst`` in the same directory.\n\nProgrammatic Use\n^^^^^^^^^^^^^^^^\n\nImport ``m2r.convert`` function and call it with markdown text.\nThen it will return converted text.\n\n.. code-block:: python\n\n from m2r import convert\n rst = convert('# Title\\n\\nSentence.')\n print(rst)\n # Title\n # =====\n #\n # Sentence.\n\nOr, use ``parse_from_file`` function to load markdown file and obtain converted\ntext.\n\n.. code-block:: python\n\n from m2r import parse_from_file\n output = parse_from_file('markdown_file.md')\n\nThis is an example of setup.py to write README in markdown, and publish it to\nPyPI as rst format.\n\n.. code-block:: python\n\n readme_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'README.md')\n try:\n from m2r import parse_from_file\n readme = parse_from_file(readme_file)\n except ImportError:\n # m2r may not be installed in user environment\n with open(readme_file) as f:\n readme = f.read()\n setup(\n ...,\n long_description=readme,\n ...,\n )\n\nSphinx Integration\n^^^^^^^^^^^^^^^^^^\n\nIn your conf.py, add the following lines.\n\n.. code-block:: python\n\n extensions = [\n ...,\n 'm2r',\n ]\n\n # source_suffix = '.rst'\n source_suffix = ['.rst', '.md']\n\nWrite index.md and run ``make html``.\n\nWhen ``m2r`` extension is enabled on sphinx and ``.md`` file is loaded, m2r\nconverts to rst and pass to sphinx, not making new ``.rst`` file.\n\nmdinclude directive\n~~~~~~~~~~~~~~~~~~~\n\nLike ``.. include:: file`` directive, ``.. mdinclude:: file`` directive inserts\nmarkdown file at the line.\n\nNote: do not use ``.. include:: file`` directive to include markdown file even if\nin the markdown file, please use ``.. mdinclude:: file`` instead.\n\nRestrictions\n------------\n\n\n* In the rst's directives, markdown is not available. Please write in rst.\n* Column alignment of tables is not supported. (rst does not support this feature)\n* Heading with overline-and-underline is not supported.\n\n * Heading with underline is OK\n\n* Rst heading marks are currently hard-coded and unchangeable.\n\n * H1: ``=``\\ , H2: ``-``\\ , H3: ``^``\\ , H4: ``~``\\ , H5: ``\"``\\ , H6: ``#``\n\nIf you find any bug or unexpected behaviour, please report it to\n`Issues <https://github.com/miyakogi/m2r/issues>`_.\n\nExample\n-------\n\nSee `example document <https://miyakogi.github.io/m2r/example.html>`_ and `its\nsource code <https://github.com/miyakogi/m2r/blob/master/docs/example.md>`_.\n\nI'm using m2r for writing user guide of `WDOM <https://github.com/miyakogi/wdom>`_.\nSo you can see it as another example. Its `HTML is\nhere <http://wdom-py.readthedocs.io/en/latest/guide/index.html>`_\\ , and `its\nsource code is here <https://github.com/miyakogi/wdom/tree/dev/docs/guide>`_.\n\nDemo editor\n^^^^^^^^^^^\n\nDemo editor of m2r is available.\nIf you are interested in m2r, please try it.\n\n`https://github.com/miyakogi/m2rdemo <https://github.com/miyakogi/m2rdemo>`_\n\nAcknowledgement\n---------------\n\nm2r is written as an extension of\n`mistune <http://mistune.readthedocs.io/en/latest/>`_\\ , which is highly extensible\npure-python markdown parser.\nWithout the mistune, I couldn't write this. Thank you!\n\nLicence\n-------\n\n`MIT <https://github.com/miyakogi/m2r/blob/master/LICENSE>`_\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Markdown and reStructuredText in a single file.",
"version": "0.3.1",
"split_keywords": [
"markdown",
"restructuredtext",
"sphinx-extension"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "255d080f56eb3d3a82d95194850c99c3",
"sha256": "aafb67fc49cfb1d89e46a3443ac747e15f4bb42df20ed04f067ad9efbee256ab"
},
"downloads": -1,
"filename": "m2r-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "255d080f56eb3d3a82d95194850c99c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16622,
"upload_time": "2022-11-17T08:12:08",
"upload_time_iso_8601": "2022-11-17T08:12:08.781941Z",
"url": "https://files.pythonhosted.org/packages/94/65/fd40fbdc608298e760affb95869c3baed237dfe5649d62da1eaa1deca8f3/m2r-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-11-17 08:12:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "miyakogi",
"github_project": "m2r",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "m2r"
}
JSON
