Using Sphinx with Markdown instead of reST

Question

I hate reST but love Sphinx. Is there a way that Sphinx reads Markdown instead of reStructuredText?

Answer 1

You can use Markdown and reStructuredText in the same Sphinx project. How to do this is succinctly documented in the Sphinx documentation.

Install myst-parser (pip install myst-parser) and then edit conf.py:

# simply add the extension to your list of extensions
extensions = ['myst_parser']

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

I've created a small example project on Github (serra/sphinx-with-markdown) demonstrating how (and that) it works. It uses Sphinx version 3.5.4 and myst-parser version 0.14.0.

In fact, MyST parser allows you to write your entire Sphinx documentation in Markdown. It supports directives and has several extensions you can enable through configuration in conf.py.

MyST parser requires Sphinx 2.1 or later. For earlier versions of Sphinx, you could use Markdown in Sphinx using recommonmark. Checkout earlier revisions of this answer to find out how.

Answer 2

The "proper" way to do that would be to write a docutils parser for markdown. (Plus a Sphinx option to choose the parser.) The beauty of this would be instant support for all docutils output formats (but you might not care about that, as similar markdown tools already exist for most). Ways to approach that without developing a parser from scratch:

1. You could cheat and write a "parser" that uses Pandoc to convert markdown to RST and pass that to the RST parser :-).

2. You can use an existing markdown->XML parser and transform the result (using XSLT?) to the docutils schema.

3. You could take some existing python markdown parser that lets you define a custom renderer and make it build docutils node tree.

4. You could fork the existing RST reader, ripping out everything irrelevant to markdown and changing the different syntaxes (this comparison might help)...
   EDIT: I don't recommend this route unless you're prepared to heavily test it. Markdown already has too many subtly different dialects and this will likely result in yet-another-one...

UPDATE: https://github.com/sgenoud/remarkdown is a markdown reader for docutils. It didn't take any of the above shortcuts but uses a Parsley PEG grammar inspired by peg-markdown.

• Doesn't yet support directives.

UPDATE: https://github.com/readthedocs/recommonmark and is another docutils reader, natively supported on ReadTheDocs. Derived from remarkdown but uses the CommonMark-py parser.

• It can convert specific more-or-less natural Markdown syntaxes to appropriate structures e.g. list of links to a toctree. * Doesn't have generic native syntax for roles.
• Supports embedding any rST content, including directives, with an ```eval_rst fenced block as well as a shorthand for directives DIRECTIVE_NAME:: ....

UPDATE: MyST is yet another docutins/Sphinx reader. Based on markdown-it-py, CommonMark compatible.

• Has a generic {ROLE_NAME}`...` syntax for roles.
• Has a generic syntax for directives with ```{DIRECTIVE_NAME} ... fenced blocks.

---

In all cases, you'll need to invent extensions of Markdown to represent Sphinx directives and roles. While you may not need all of them, some like .. toctree:: are essential.
This I think is the hardest part. reStructuredText before the Sphinx extensions was already richer than markdown. Even heavily extended markdown, such as pandoc's, is mostly a subset of rST feature set. That's a lot of ground to cover!

Implementation-wise, the easiest thing is adding a generic construct to express any docutils role/directive. The obvious candidates for syntax inspiration are:

• Attribute syntax, which pandoc and some other implementations already allow on many inline and block constructs. For example `foo`{.method} -> `foo`:method:.
• HTML/XML. From <span class="method">foo</span> to the kludgiest approach of just inserting docutils internal XML!
• Some kind of YAML for directives?

But such a generic mapping will not be the most markdown-ish solution... Currently most active places to discuss markdown extensions are https://groups.google.com/forum/#!topic/pandoc-discuss, https://github.com/scholmd/scholmd/

This also means you can't just reuse a markdown parser without extending it somehow. Pandoc again lives up to its reputation as the swiss army knife of document conversion by supporting custom filtes. (In fact, if I were to approach this I'd try to build a generic bridge between docutils readers/transformers/writers and pandoc readers/filters/writers. It's more than you need but the payoff would be much wider than just sphinx/markdown.)

---

Alternative crazy idea: instead of extending markdown to handle Sphinx, extend reStructuredText to support (mostly) a superset of markdown! The beauty is you'll be able to use any Sphinx features as-is, yet be able to write most content in markdown.

There is already considerable syntax overlap; most notably link syntax is incompatible. I think if you add support to RST for markdown links, and ###-style headers, and change default `backticks` role to literal, and maybe change indented blocks to mean literal (RST supports > ... for quotations nowdays), you'll get something usable that supports most markdown.

Answer 3

This doesn't use Sphinx, but MkDocs will build your documentation using Markdown. I also hate rst, and have really enjoyed MkDocs so far.

Answer 4

Update May 2021: recommonmark is deprecated in favour of myst-parser (thanks astrojuanlu)

Update: this is now officially supported and documented in the sphinx docs.

It looks like a basic implementation has made it's way into Sphinx but word has not gotten round yet. See github issue comment

install dependencies:

pip install commonmark recommonmark

adjust conf.py:

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

Answer 5

Markdown and ReST do different things.

RST provides an object model for working with documents.

Markdown provides a way to engrave bits of text.

It seems reasonable to want to reference your bits of Markdown content from your sphinx project, using RST to stub out the overall information architecture and flow of a larger document. Let markdown do what it does, which is allow writers to focus on writing text.

Is there a way to reference a markdown domain, just to engrave the content as-is? RST/sphinx seems to have taken care of features like toctree without duplicating them in markdown.

Answer 6

I recommend using MyST Markdown. This is a flavor of Markdown that was designed to bring in the major features of reStructuredText. MyST stands for Markedly Structured Text, and can be thought of as "rST but with Markdown".

MyST is a superset of the CommonMark standard, and it is defined as a collection of discrete extensions to CommonMark via the markdown-it-py package). This means that CommonMark syntax works out-of-the-box with MyST, but you can also use more syntax features if you wish.

MyST has syntax for virtually every feature in reStructuredText, and it is tested against the full Sphinx test suite to ensure that the same functionality can be re-created. For example:

Here is how you write a directive in MyST:

```{directivename} directive options
:key: value
:key2: value2

Directive content
```

And here is how you write a role in MyST

Here's some text and a {rolename}`role content`

The Sphinx parser for MyST Markdown also has some nice Sphinx-specific features, like using Markdown link syntax ([some text](somelink)) to also handle cross-references in Sphinx. So for example, you can define a label in MyST, and reference it, like so:

(my-label)=
# My header

Some text and a [cross reference](my-label).

For a more complete list of MyST Markdown syntax, a good reference is the Jupyter Book cheatsheet, which has a list of many common document needs and the respective MyST syntax to accomplish it. (MyST was created as a component of Jupyter Book, though it exists as a totally standalone project from a technical perspective).

MyST is now the recommended Markdown tool for Sphinx in the Sphinx docs as well as the ReadTheDocs documentation.

To add the MyST Parser to your Sphinx documentation, simply do the following:

pip install myst-parser

And in conf.py, add:

extensions = [
  ...
  "myst_parser",
  ...
]

Your Sphinx documentation will now be able to parse CommonMark markdown as well as the extended MyST Markdown syntax! Check out the MyST Documentation for more information!

I hope that this helps clarify some things!

Answer 7

This is now officially supported: http://www.sphinx-doc.org/en/stable/markdown.html

See also https://myst-parser.readthedocs.io/en/latest/syntax/optional.html for extensions, including linkify to make urls automatic links.

Answer 8

I went with Beni's suggestion of using pandoc for this task. Once installed the following script will convert all markdown files in the source directory to rst files, so that you can just write all your documentation in markdown. Hope this is useful for others.

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

Answer 9

Here’s a new option. MyST adds some features to Markdown that allow Sphinx to build docs like rst does. https://myst-parser.readthedocs.io/en/latest/

Answer 10

There is a workaround.
The sphinx-quickstart.py script generates a Makefile.
You can easily invoke Pandoc from the Makefile every time you'd like to generate the documentation in order to convert Markdown to reStructuredText.

Answer 11

Note that building documentation using maven and embedded Sphinx + MarkDown support is fully supported by following maven plugin :

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Answer 12

This is an update to the recommonmark approach.

pip install recommonmark

Personally I use Sphinx 3.5.1, so

# for Sphinx-1.4 or newer
extensions = ['recommonmark']

Check the official doc here.