Skip to content

Instantly share code, notes, and snippets.

Created Sep 19, 2014
What would you like to do?


experimental implementation to use markdown as input of Sphinx.

How to install

  1. install remarkdown

    $ pip install
    $ curl -LO
    $ mv markdown.parsley lib/python2.7/site-packages/remarkdown
  2. put to your environment

  3. configure your sphinx project (

    Add following settings to

    sys.path.insert(0, '.')
    source_suffix = '.md'
  4. write!

from docutils.core import Publisher
class MarkdownPublisher(Publisher):
def __init__(self, *args, **kwargs):
Publisher.__init__(self, *args, **kwargs)
# replace parser FORCELY
from remarkdown.parser import MarkdownParser
self.reader.parser = MarkdownParser()
def publish(self):
# set names and ids attribute to section node
from docutils import nodes
for section in self.document.traverse(nodes.section):
titlenode = section[0]
name = nodes.fully_normalize_name(titlenode.astext())
self.document.note_implicit_target(section, section)
def setup(_):
# replace Publisher
import sphinx.environment
sphinx.environment.Publisher = MarkdownPublisher

This comment has been minimized.

Copy link

@ericholscher ericholscher commented Feb 7, 2015

This is great. remarkdown seems to be breaking on raw HTML snippets though. But it's a great start! :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment