Skip to main content

A docutils-compatibility bridge to markdown, enabling you to write markdown with support for tables inside of docutils & sphinx projects.

Project description

A docutils-compatibility bridge to MarkdownParser and CommonMark.

This allows you to write markdown inside of docutils & sphinx projects.

This was built due to limitations of the existing markdown parsers supported by sphinx, specifically recommonmark. Features such as support for tables have been added to this extension.


Getting Started

To use sphinx-markdown-parser inside of Sphinx only takes 2 steps. First you install it:

pip install sphinx-markdown-parser

Then add this to your Sphinx

# for MarkdownParser
from sphinx_markdown_parser.parser import MarkdownParser

def setup(app):
    app.add_source_suffix('.md', 'markdown')
    app.add_config_value('markdown_parser_config', {
        'auto_toc_tree_section': 'Content',
        'enable_auto_doc_ref': True,
        'enable_auto_toc_tree': True,
        'enable_eval_rst': True,
        'enable_inline_math': True,
        'enable_math': True,
    }, True)

# for CommonMarkParser
from recommonmark.parser import CommonMarkParser

def setup(app):
    app.add_source_suffix('.md', 'markdown')
    app.add_config_value('markdown_parser_config', {
        'auto_toc_tree_section': 'Content',
        'enable_auto_doc_ref': True,
        'enable_auto_toc_tree': True,
        'enable_eval_rst': True,
        'enable_inline_math': True,
        'enable_math': True,
    }, True)

This allows you to write both .md and .rst files inside of the same project.


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

# At top on (with other import statements)
import recommonmark
from recommonmark.transform import AutoStructify

# At the bottom of
def setup(app):
    app.add_config_value('markdown_parser_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)

See for a full example.

AutoStructify comes with the following options. See for more information about the specific features.

  • enable_auto_toc_tree: enable the Auto Toc Tree feature.

  • auto_toc_tree_section: when True, Auto Toc Tree will only be enabled on section that matches the title.

  • enable_auto_doc_ref: enable the Auto Doc Ref feature. Deprecated

  • enable_math: enable the Math Formula feature.

  • enable_inline_math: enable the Inline Math feature.

  • enable_eval_rst: enable the evaluate embedded reStructuredText feature.

  • url_resolver: a function that maps a existing relative position in the document to a http link


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.

Why a bridge?

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.

Why another bridge to docutils?

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_markdown_parser-0.1.6.tar.gz (30.3 kB view hashes)

Uploaded Source

Built Distribution

sphinx_markdown_parser-0.1.6-py2.py3-none-any.whl (16.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page