Skip to content

Instantly share code, notes, and snippets.

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

sphihxcontrib_markdown

experimental implementation to use markdown as input of Sphinx.

How to install

  1. install remarkdown

    $ pip install https://github.com/sgenoud/remarkdown/archive/master.zip
    $ curl -LO https://raw.githubusercontent.com/sgenoud/remarkdown/master/remarkdown/markdown.parsley
    $ mv markdown.parsley lib/python2.7/site-packages/remarkdown
    
  2. put sphinxcontrib_markdown.py to your environment

  3. configure your sphinx project (conf.py)

    Add following settings to conf.py:

    sys.path.insert(0, '.')
    extensions.append('sphinxcontrib_markdown')
    source_suffix = '.md'
    
  4. write index.md!

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):
Publisher.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())
section['names'].append(name)
self.document.note_implicit_target(section, section)
def setup(_):
# replace Publisher
import sphinx.environment
sphinx.environment.Publisher = MarkdownPublisher
@ericholscher

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