将狮身人面像与Markdown结合使用，而不是RST

Question

我讨厌RST，但喜欢狮身人面像。有一种方法可以使狮身人面像读取markdown而不是reStructuredText吗？

Answer 1

“正确的方法”是为降价编写docutils parser。 （加上Sphinx选项来选择解析器。）它的优点是可以立即支持所有docutils输出格式（但是您可能并不在意，因为大多数降价工具已经存在）。无需从头开发解析器的方法：

• 您可以作弊并编写一个使用Pandoc将markdown转换为RST并将其传递给RST解析器的“解析器”：-）。

• 您可以使用现有的markdown-> XML解析器，并将结果（使用XSLT？）转换为docutils架构。

• 您可以使用一些existing python markdown parser来定义自定义渲染器，并使其构建docutils节点树。

• 您可以派生现有的RST阅读器，删除与降价无关的所有内容并更改不同的语法（this comparison可能会有所帮助）...编辑：除非您准备好对其进行大量测试，否则我不建议您使用此路线。 Markdown已经有太多不同的方言，这很可能会导致另一方...

UPDATE： https://github.com/sgenoud/remarkdown是docutils的降价阅读器。它没有采用上述任何快捷方式，而是使用了受Parsley启发的peg-markdown PEG语法。 Doesn't yet支持指令。

UPDATE：https://github.com/rtfd/recommonmark是另一个docutils阅读器，ReadTheDocs本身受支持。从remarkdown派生，但使用CommonMark-py解析器。不支持指令，但是can convert或多或少的自然Markdown语法适用于适当的结构，例如toctree的链接列表。对于其他需求，```eval_rst fenced block允许您嵌入任何rST指令。

---

在所有情况下，您需要发明Markdown的扩展名以表示```eval_rst。尽管您可能不需要全部，但有些Sphinx directives and roles是必不可少的。我认为这是最困难的部分。 Sphinx扩展之前的reStructuredText已经比markdown丰富。即使是大幅扩展的降价促销活动，例如.. toctree::，也大多是rST功能集的子集。有很多方面需要解决！

实施方面，最简单的方法是添加通用构造以表达任何docutils角色/指令。语法启发的明显候选者是：

• 属性语法，pandoc和其他一些实现已经允许在许多内联和块构造中使用。例如pandoc's-> `foo`{.method}。
• HTML / XML。从`foo`:method:到仅插入docutils内部XML的kludgiest方法！
• 某种针对指令的YAML？

但是这样的通用映射将不是降价幅度最大的解决方案...当前讨论降价扩展的最活跃地方是<span class="method">foo</span>，https://groups.google.com/forum/#!topic/pandoc-discuss

这也意味着您不能不以某种方式扩展Markdown解析器。 Pandoc通过支持https://github.com/scholmd/scholmd/，再次实现了其作为文档转换的瑞士军刀的声誉。 （实际上，如果我要采用这种方法，我会尝试在docutils读取器/变压器/编写器与pandoc读取器/过滤器/编写器之间建立通用的桥梁。这超出了您的需求，但收益将远远超过狮身人面像/降价。）

---

[另一种疯狂的想法：与其扩展markdown以处理Sphinx，不如扩展reStructuredText以支持（主要是）markdown的超集！这样做的好处是您可以按原样使用任何Sphinx功能，但仍可以在markdown中编写大多数内容。

已经有custom filtes；最明显的是链接语法不兼容。我认为，如果您为markdown链接和considerable syntax overlap样式的标题添加了对RST的支持，并且将默认的###角色更改为文字，并且可能将缩进的块更改为文字（现在RST支持`backticks`来引用），您'将获得支持大多数降价促销的可用商品。

Answer 2

您可以在同一Sphinx项目中使用Markdown和reStructuredText。在> ...上简要记录了如何执行此操作。

安装重新标记（Read The Docs），然后编辑pip install recommonmark：

conf.py

---

我创建了一个小示例项目

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

，以演示其工作方式（及工作方式）。它使用CommonMark 0.5.4和recommonmark 0.4.0。

Answer 3

这不使用Sphinx，但是on Github (serra/sphinx-with-markdown)将使用Markdown构建文档。我也讨厌rst，到目前为止，我非常喜欢MkDocs。

Answer 4

更新：现已得到正式支持，并记录在MkDocs中。

看来基本的实现已将其引入Sphinx，但尚未解决。 sphinx docs

安装依赖项：

See github issue comment

调整pip install commonmark recommonmark ：

conf.py

Answer 5

Markdown和ReST做不同的事情。

RST提供了用于处理文档的对象模型。

Markdown提供了一种雕刻文字的方法。

似乎很想从您的狮身人面像项目中引用您的Markdown内容，使用RST存根整个信息结构和更大文档的流程。让markdown做它所做的事情，这使作者可以专注于编写文本。

是否有一种引用标记降价域的方法，只是按原样雕刻内容？ RST / sphinx似乎已经照顾了

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

之类的功能，而没有在markdown中复制它们。

Answer 6

我赞同贝尼（Beni）建议使用pandoc来完成此任务。安装后，以下脚本会将源目录中的所有markdown文件转换为rst文件，以便您可以将所有文档写入markdown中。希望这对其他人有用。

toctree

Answer 7

现在已正式支持：

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

Answer 8

有一种解决方法。sphinx-quickstart.py脚本生成一个Makefile。您可以在每次想要生成文档时轻松地从Makefile中调用Pandoc，以将Markdown转换为reStructuredText。

Answer 9

请注意，通过以下maven插件完全支持使用maven和嵌入式Sphinx + MarkDown支持构建文档：

http://www.sphinx-doc.org/en/stable/markdown.html

https://trustin.github.io/sphinx-maven-plugin/index.html

Answer 10

这是一个新选项。 MyST向Markdown添加了一些功能，这些功能使Sphinx可以像rst一样构建文档。

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>