Sphinx: Would be great to have Markdown output support from Sphinx

[Tagar]

Subject: Would be great to have Markdown output support from Sphinx

Problem

• As described on https://stackoverflow.com/questions/13396856/markdown-output-for-sphinx-based-documentation that would be extremely helpful for Sphinx to natively support Markdown output.

Thank you.

[tk0miya]

-1; we don't have enough time to implement it. Please make it as an extension.

[Tagar]

@tk0miya with over 20 thumbs up on this request, would you please consider reopening this issue ?

If you provide some pointers on how to best tackle this, I (or somebody else) can try to get on this improvement.

Thank you.

[tk0miya]

Reopened. But it does not mean sphinx-core team develops it. In addition, Sphinx-extension is much appropriate for such case to me.

[stephenfin]

@Tagar You're going to want to implement a builder. There are many examples of this in tree. The main issue I'd see is that you'll need to develop a mapping of all docutil and Sphinx node types to Markdown equivalents. You might choose to ignore many of these and simply strip formatting, as the plain text builder does, for a first pass.

[codejamninja]

I built a builder for this. You can find it at the links below.

https://pypi.org/project/sphinx-markdown-builder
https://github.com/codejamninja/sphinx-markdown-builder

pip3 install sphinx-markdown-builder

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

Credit to Chris Wrench for the docutils markdown writer base code (which I am improving).

This is super alpha, so there are definitely things that don't work (for example, tables and header links). Feel free to contribute. I will definitely be improving this.

[stephenfin]

As an FYI, it looks like nb2plots includes something similar too. Might want to check that out and see how that compares

[codejamninja]

This isn't a sphinx plugin or builder, but it definitely has a more put together markdown writer.

https://github.com/matthew-brett/nb2plots/blob/master/nb2plots/doctree2md.py

I think I might integrate with this plugin. Thanks @stephenfin!

[codejamninja]

I replaced Chris Wrench's markdown writer with Matthew Brett's doctree2md markdown writer (from nb2plots). sphinx-markdown-builder is working great now.

Thanks again @stephenfin for recommending nb2plots as the writer, it works amazing.

[codejamninja]

Please let me know if there are any bugs with it. This issue can prob be closed now.

[tk0miya]

Now I'm closing this again.
Thanks,