Markdown capable Sphinx

[shimizukawa]

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

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/825
• Originally reported by: Hibou57
• Originally created at: 2011-11-20T07:02:20.814

[shimizukawa]

From Robert Lehmann on 2011-11-21 08:57:50+00:00

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.

[shimizukawa]

From sgenoud on 2013-08-25 15:12:13+00:00

I have started to work on a markdown parser that generates a Docutils doctree. You can have a look at it here: https://github.com/sgenoud/remarkdown

[shimizukawa]

From Matt Hickford on 2014-09-14 17:43:10+00:00

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

[shimizukawa]

From Georg Brandl on 2014-09-17 07:52:05+00:00

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.

[shimizukawa]

From Takeshi Komiya on 2014-09-19 04:26:19+00:00

While ago, I tried to combine Sphinx and remarkdown parser.
https://gist.github.com/31b553b4bd4bf987731e

I succeeded parsing markdown with Sphinx.
but I could not link other documents from index.md
because markdown is not extensible (I need toctree directive!).

I hope this monkey patch will help for discussion :-)

[csillag]

+1

[TomasTomecek]

This is the only reason I am not using sphinx.

[saily]

we use Sphinx, but often i have to convert documents from md to rst using pandoc, because people are using markdown editors to write their docs. so same here, +1

[miroi]

Enabling some md-files within Sphinx documentation would be great. My support for this feature !

[cekees]

+1. Since #1747 is now merged, at least a limited capability seems within easy reach. Are there any examples yet or ways some of us can help?

[michaelaye]

Is this still being worked on? I'm also in the boat that learning another input language hinders my documentation efforts. Especially with all the nice cookiecutter projects that automatically setup things for a new project, plus integration into readthedocs.org, it would be so cool if I could just start to write docs in Markdown.

[mitya57]

In Python-Markdown, we investigated if we could use the Docutils element tree, but it looks like it's not suitable for us. See the discussion in Python-Markdown/markdown#420.

Here is an attempt by someone else to create a Markdown parser for Docutils.

[shimizukawa]

Please try:

pip install commonmark recommonmark

conf.py

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

It's still limited, but usable.

[lehmannro]

I think, in all honesty, Python-Markdown didn't do its due diligence and rejected Docutils too easily. The mere existence of other Markdown parsers for Docutils should have shown it is indeed a fit.

[AJ-Acevedo]

I'd be willing to contribute to a bounty on Bountysource to get native markdown support in Sphinx.

[ahicks92]

+1 as well.
Many of those of us who are visually impaired hate ReST with the burning intensity of a thousand suns. There's a lot of emphasis on getting alignments and character counts just right, and that's annoying when you quite literally cant' see the supposed beauty of the text file that no one really reads in that format anymore anyway. Both headings and tables are something I consider significantly painful because of this, and they're both essential to documenting. But I get that I'm in a minority here.

[thedmi]

+1

[bojanv91]

+1

[nelsonam]

+1

I'm with @camlorn it's really difficult to figure out why there's an error when it turns out there's one extra space or something.

[lsbardel]

Please please please,
let's get markdown working on sphinx/docutils.
restructuredText is not a great syntax (being polite),
and I've used it for quite some time 😢
How can we speed up this ticket @birkenfeld? 🙏

[shimizukawa]

Actually, sphinx can build Markdown document by using:

pip install commonmark recommonmark

conf.py

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

It's still limited, but usable.

---

Now I lock this issue. If there are any problem, please file another ticket. Thanks.

[birkenfeld]

Well, what is missing is more documentation and "publicizing" of this :)

[tk0miya]

Documented at #3373. Thank you @TimKam !