Markdown output for Sphinx based documentation

Question

I found myself with a use case, where in addition to generating HTML and PDF from my Sphinx based documentation sources, I would also like to generate a Markdown version of the reStructuredText source files.

My preliminary research didn't find any core or extension support for this in Sphinx. Other than manually using pandoc or creating a new Sphinx extension for the task, is there be a simpler/more integrated solution for this?

I haven't seen any existing extension. Before your second paragraph, my first idea was to suggest Pandoc :-) So I guess that's your best bet. — Reinout van Rees, Nov 18 '12 at 16:54
@ReinoutvanRees: I am using pandoc at moment. Maybe I'll probe the Sphinx community to see if there is any interest in implementing something like this and give it a go. :) — Pedro Romano, Nov 18 '12 at 16:57
possible duplicate of [Using sphinx with Markdown instead of RST](http://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst) — the_drow, May 07 '13 at 23:46

score 27 · Accepted Answer · answered Nov 20 '12 at 16:53

I didn't find anything which could take reStructuredText files and convert them to Markdown except for Pandoc, so I wrote a custom writer for Docutils (the reference implementation of reStructuredText and what Sphinx is built upon). The code is available on GitHub.

Note that it is only an initial implementation: it handles any reStructuredText document without error (tested against the standard.txt test document from the Docutils source repository) but many of the reStructuredText constructs (e.g. substitutions, raw directives etc.) are not supported and so not included in the Markdown output. I hope to add support for links, code blocks, images and tables: any help towards this is more than welcome - just go ahead and fork the code.

It seems that to add another writer/output format to Sphinx you need to add a "builder" using an extension.

Thanks, Chris for getting this started. I created a builder extension for this. https://github.com/codejamninja/sphinx-markdown-builder — Clay Risser, Nov 11 '18 at 07:26

Tagar · Answer 2 · 2019-07-08T03:59:15.943

Update Nov'18: sphinx-markdown-builder is now available - thanks to @Jam Risser :

Installation

pip3 install sphinx-markdown-builder

Dependencies

Python 3

Usage

Load extension in configuration.

conf.py

extensions = [
    'sphinx_markdown_builder'
]

If using recommonmark, make sure you explicitly ignore the build files as they will conflict with the system.

conf.py

exclude_patterns = [
    'build/*'
]

Build markdown files with Makefile

make markdown

Build markdown files with sphinx-build command

cd docs
sphinx-build -M markdown ./ build

References

ps. Outdated original answer (since sphinx-markdown-builder is now available): Created feature request for direct Markdown output support on Sphinx project site: https://github.com/sphinx-doc/sphinx/issues/4219 Thanks everyone who upvoted that github request - that made the difference!

score 0 · Answer 3 · answered May 07 '13 at 23:43

If you'd like to use pandoc why won't you simply change the Makefile Sphinx generates when you run sphinx-quickstart.py for the first time to convert the reStructuredText to Markdown?
It's the easiest solution, although Chris's solution should work as well if you incorporate it into the Makefile.

Markdown output for Sphinx based documentation

3 Answers3

Linked

Related