Get started¶

We have documented how to get started with Commonmark inside of Sphinx. You simply:

pip install recommonmark

Then in your conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {'.md': CommonMarkParser}

source_suffix = ['.rst', '.md']

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

Example Project¶

You can see this in action in my sphinx-markdown-test repo on GitHub. You can also see a rendered version hosted on Read the Docs.

How it works¶

The way this project works is that it allows Commonmark files to be parsed into docutils nodes. That means that everything downstream of the parser works the same as if the content came from RST. This allows the content to slot into Sphinx and other RST based tools without much effort.

There are some caveats where certain Sphinx & docutils directives depend on the internal structure of RST. We would like to eventually build a bridge from Commonmark to the Sphinx directives, which would give a lot of the power of Sphinx to the Commonmark content.

We are looking at ways to handle this in the future, and hope to eventually bring the full power of RST and Sphinx into the Commonmark ecosystem.

Limitations¶

It should be noted that Commonmark doesn’t support a lot of the concepts that RST lets you represent. In particular, there is no standardized way in Commonmark to represent inline or block levels constructs. So things like the toctree directive and :ref: markup don’t have an analog.

There is a proposed draft to the Commonmark spec to allow a similar syntax. We are investigating adding support to this in recommonmark, but we don’t want to implement a standard prematurely.

Intended Usage¶

We think that Sphinx’s power to reference code and other programming concepts is quite powerful. However, all content doesn’t need this ability. When you’re writing content that just needs to have basic text formatting and links, Commonmark is a great option for this.

We imagine that API reference documentation will continue to be authored in RST for quite some time. Also index pages and other reference heavy content will continue to be RST. FAQ’s, blog posts, and other less reference heavy content is a great candidate for writing in Commonmark.

Feedback¶

This is a new release, so there are likely some missing pieces to our integration. Go ahead and try it out. Please file features ideas and bug reports on the recommonmark bug tracker.