Markdown输出，用于基于Sphinx的文档


Markdown output for Sphinx based documentation

我发现自己有一个用例，除了从基于Sphinx的文档源生成HTML和PDF之外，我还想生成reStructuredText源文件的Markdown版本。

我的初步研究没有在Sphinx中找到对此的任何核心或扩展支持。 除了手动使用pandoc或为该任务创建新的Sphinx扩展之外，还有其他更简单/更集成的解决方案吗？

相关讨论

除了Pandoc之外，我没有发现任何可以将reStructuredText文件转换为Markdown的文件，因此我为Docutils(reStructuredText的参考实现以及Sphinx的构建)编写了自定义编写器。该代码可在GitHub上获得。

请注意，这只是一个初始实现：它可以毫无错误地处理任何reStructuredText文档(已根据Docutils源存储库中的standard.txt测试文档进行了测试)，但是不支持许多reStructuredText构造(例如，替换，原始指令等)，并且因此不包括在Markdown输出中。我希望增加对链接，代码块，图像和表的支持：对此的任何帮助都非常受欢迎-只需继续编写代码即可。

似乎要向Sphinx添加其他编写器/输出格式，您需要使用扩展名添加"构建器"。

相关讨论

18年11月更新：sphinx-markdown-builder现在可用-感谢@Jam Risser：

安装

1
pip3 install sphinx-markdown-builder

依存关系

Python 3

用法

在配置中加载扩展。

conf.py

1
2
3
extensions = [
    'sphinx_markdown_builder'
]

如果使用recommonmark，请确保您显式忽略构建文件，因为它们将与系统冲突。

conf.py

1
2
3
exclude_patterns = [
    'build/*'
]

用Makefile构建markdown文件

1
make markdown

使用sphinx-build命令构建markdown文件

1
2
cd docs
sphinx-build -M markdown ./ build

参考文献

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

ps。原始答案已过时(因为sphinx-markdown-builder现在可用)：
在Sphinx项目站点上创建了直接Markdown输出支持的功能请求：
https://github.com/sphinx-doc/sphinx/issues/4219
感谢支持该github请求的每个人-有所作为！

如果您想使用pandoc，为什么不直接在第一次运行sphinx-quickstart.py时更改Sphinx生成的Makefile，以将reStructuredText转换为Markdown？
这是最简单的解决方案，尽管如果将Chris的解决方案合并到Makefile中，它也可以正常工作。