征求意见：在 Markdown 中包含代码片段的语法应该是什么？（来自外部文件）

Question

我一直在使用 降价 最近。

我对 Markdown 的最大问题之一是 Markdown 没有用于在文档中包含文件的语法（相对于，比方说， listings LaTeX 包）。

我想扩展 Markdown 以支持将整个和部分文件作为代码片段包含在内。例如，它可能看起来像这样：

![:include src/foo/bar.rb](10-20)

这会将内容 bar.rb 第 10-20 行作为我的文档的 code 堵塞。理由是

• 文档可以随着代码的更改而更新。（与复制和粘贴总是会过时）
• 然后您可以对文档中的确切代码进行单元测试

我的问题是：

1. 语法应该是什么？
2. 这已经完成了吗，而我却错过了？

Answer 1

我更倾向于提出一种扩展 Markdown 语法的通用方法，然后使用它来提供对包含函数的支持。例如，您可以定义如下语法（我并不是真正建议这种特定语法，只是一个示例）：

[[command: arg arg arg...]]

..在哪里 command 指的是 Markdown 解析器无法理解的命令，但可以回调到其他东西来处理它。然后，您可以构建一个包含函数，该函数将与 Markdown 一起使用，但实际上并不是它的一部分。就像是：

[[include: src/foo/bar.md]]

哦，如果你这样做，我可能不会提供包含部分文件的方法，至少不会使用行号 - 因为这意味着如果你更改了文件的长度，你必须返回并编辑所有包含调用文档，这实际上使重用变得更加困难（如果您能想出一种标记部分的方法，那可能会更好）。

Answer 2

我通常倾向于看看是否可以以合理的方式使用现有语法。目前，

    ![Example Photo](http://example.com/example.jpg)

语法及其相关语法用于在文本中包含图像。与此相类似，

    +[Generic Heading](http://example.com/heading.txt)

或者

    +[Local Heading](file:///dir/a/b/c/example.txt)

可用于包含文本。在这种情况下，方括号中的文本就像 alt-text 内嵌图像的属性：它包含对所包含文件的简短、人类可理解的描述。

使用 + 对我来说很直观：它的意思是 添加 将此文件的内容添加到此处的此文档中。

Answer 3

我来晚了一点，抱歉。但restructedText已经支持这一点：http://docutils.sourceforge.net/docs/ref/rst/directives.html#include-an-external-document-fragment