Using sphinx with Markdown instead of RST

Question

I hate RST but love sphinx. Is there a way that sphinx reads markdown instead of reStructuredText?

Answer 1

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).

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

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

• You could fork the existing RST reader, ripping out everything irrelevant to markdown and changing the few different syntaxes...

In all cases, you'll need to invent extensions of Markdown to represent Sphinx directives (e.g. toctree).