Issues

Issue #825 new

Markdown capable Sphinx

Hibou57
created an issue

This is not a bug notification, this is a feature suggestion.

Markdown being more natural (make use of instinctive common practices in mail, forum, blog, and so on), more readable (make use of widespread typographic conventions), being far more popular, being far more widely supported in many ways, and being as much capable as ReST to write documentation, a Markdown capable Sphinx would be great and would help a lot (would also help to enforce a standard).

Comments (7)

  1. Robert Lehmann

    You'd need to generate a Docutils doctree from Markdown documents. StackOverflow has an useful discussion on that topic. http://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst#2487862

    While I, personally, think ReST is perfectly fine (and would disagree with your point about enforcing standards by introducing another input language) we are happy to accept patches. Other than that I don't think this is a top priority task for any contributor and am tempted to close as wontfix.

  2. Mirth Hickford

    Markdown is a pervasive format made by popular by GitHub, Stack Overflow and Reddit. For better or worse, it's familiar to millions of people.

    It shouldn't be necessary to learn a new markup language to document your project. Out-the-box support for Markdown in Sphinx would let swathes of people write and edit documentation who were previously discouraged by the barrier of learning ReStructuredText.

    Note also this is a hugely popular request on Stack Overflow https://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst

  3. Georg Brandl repo owner

    Yep, I know and I'd welcome Markdown support in Sphinx.

    But it's unlikely that I will find time to implement it, and there may be some hairy questions involved (Markdown syntax is less powerful than rst, so how do you map the roles/directives?)

    If somebody makes a reasonably complete pull request, I'm ready to discuss. sgenoud's parser could be a nice starting point.

  4. Log in to comment