Name: recommonmark
Owner: Read the Docs
Description: A markdown parser for docutils
Created: 2015-07-28 17:42:59.0
Updated: 2018-05-21 14:34:26.0
Pushed: 2018-05-07 09:48:27.0
Homepage: null
Size: 111
Language: Python
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
A docutils-compatibility bridge to CommonMark.
This allows you to write CommonMark inside of Docutils & Sphinx projects.
Documentation is available on Read the Docs: http://recommonmark.readthedocs.org
To use recommonmark inside of Sphinx only takes 2 steps.
First you install it:
install recommonmark
Then add this to your Sphinx conf.py:
recommonmark.parser import CommonMarkParser
ce_parsers = {
'.md': CommonMarkParser,
ce_suffix = ['.rst', '.md']
This allows you to write both .md and .rst files inside of the same project.
For all links in commonmark that aren't explicit URLs, they are treated as cross references with the :any: role. This allows referencing a lot of things including files, labels, and even objects in the loaded domain.
AutoStructify makes it possible to write your documentation in Markdown, and automatically convert this into rST at build time. See the AutoStructify Documentation for more information about configuration and usage.
To use the advanced markdown to rst transformations you must add AutoStructify to your Sphinx conf.py.
top on conf.py (with other import statements)
rt recommonmark
recommonmark.transform import AutoStructify
the bottom of conf.py
setup(app):
app.add_config_value('recommonmark_config', {
'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)
See https://github.com/rtfd/recommonmark/blob/master/docs/conf.py for a full example.
AutoStructify comes with the following options. See http://recommonmark.readthedocs.org/en/latest/auto_structify.html for more information about the specific features.
You can run the tests by running tox in the top-level of the project.
We are working to expand test coverage, but this will at least test basic Python 2 and 3 compatability.
Many python tools (mostly for documentation creation) rely on docutils.
But docutils only supports a ReStructuredText syntax.
For instance this issue and this StackOverflow question show that there is an interest in allowing docutils
to use markdown as an alternative syntax.
recommonmark uses the python implementation of CommonMark while remarkdown implements a stand-alone parser leveraging parsley.
Both output a docutils document tree and provide scripts
that leverage docutils for generation of different types of documents.
recommonmark is mainly derived from remarkdown by Steve Genoud and leverages the python CommonMark implementation.
It was originally created by Luca Barbato, and is now maintained in the Read the Docs (rtfd) GitHub organization.