在另一个 markdown 文档中嵌入一个文档

Question

有没有一种方式能够嵌入一个Markdown文档（或者它的子格式 - 我使用的是PanDoc）到另一个Markdown文档中，除了使用jQuery().load(url)？ 我想要一个包含main.md、chapter1.md和chapter2.md这样的文档，其中main.md会自动加载chapter1.md和chapter2.md。 main.md会在两个章节之间包含文本，例如： main.md:

Some opening text...
...
[chapter1.md]

Some additional text...
...
[chapter2.md]
...
something else.

所以我不能使用cat *.md > final.md的方法

- Tahnoon Pasha

Answer 1

Markdown本身没有包含文件的符号，这相当糟糕。

Pandoc有一个示例，它使用自定义的Haskell过滤器在代码块中包含文件，但是这个方法 a. 在文本周围保留了一个代码块（更重要的是）b. 不解析新文件为Markdown，而且老实说我的Haskell水平还不足以解决这个问题。

但是，您可以通过进行预处理传递, 使用perl *。 我假设每个包含都以类似上面显示的形式单独占一行。

perl -ne 's/^\[(.+)\].*/`cat $1`/e;print' main.md > final.md

*我不喜欢不得不使用perl，但是sed缺乏使用匹配模式从文件中读取并确定名称的能力。

- Oliver Matthews

---

非常感谢@OliverMatthews。我可能会使用Python而不是Perl，但预处理听起来像个好主意。 - Tahnoon Pasha

在花费了数十个小时寻找一种可行且快速的方法来实现 Pandoc 中的包含功能后，终于找到了解决方案。谢谢！ - certainlyakey

这是我的 Perl 语句现在的样子 - 它稍微修改了一下，以便包含带有空格的文件路径，并兼容于路径搜索 ST 插件（如 AutoFileName）。此外，它已经转义以在 ST 构建系统中工作。语法是 #(path/to/file)：perl -ne 's/^#\\((.+)\\).*/cat "\$1"/e;print' ${file_base_name}.md > result.md。 - certainlyakey

对于这个_markdown_的问题，我感到很沮丧。但是，你可能做出了最不痛苦的解决方法。 - WestCoastProjects

Answer 2

如果您不想在正文中包含子章节，可以简单地在主章节中插入链接。这样就不需要预处理步骤。

如Oliver Matthews所写，您可以使用perl编写自己的预处理步骤。

或者您可以使用现有的预处理器，例如m4或cpp（C预处理器），允许包含文件。然而，cpp可能无法很好地处理文档中的C代码部分，尤其是当其中有更多的include指令时。

互联网上也提供了一些工具链，可以将单独的markdown文档组合成一个更大的文档。但很遗憾，我目前无法访问我的书签备份。

以下是类似的问题及其答案：Markdown and including multiple files，尽管答案并未解释如何在其他文字之间插入子章节。

- Sebastian

---

我考虑使用cpp（并使用#include），但是发现头文件也以#开头，这可能会很麻烦。 对于那些喜欢有点玄学的人来说，总是有funnelweb可用（这可能是我个人会使用的东西，但我尝试将其限制为您已安装的内容）。 - Oliver Matthews

Answer 3

使用类似于维基链接的语法 ![[chapter1.md]] 的@Oliver Matthews' answer的递归版本

---

parseMd.sh

#!/usr/bin/env bash
perl -ne 's#^!\[\[(.+?)\]\].*#`'$0' "$1"`#e;print' "$@"

并像这样使用它

./parseMd.sh main.md > final.md

---

与 pandoc 一起使用

pandoc <(./parseMd.sh main.md) -o final.pdf

- Madacol

Answer 4

最近我一直在阅读这些帖子，尽管它们现在有点旧了，还有Markdown和包含多个文件的帖子。对于这一切，我相对来说还是新手，所以我无法让Sethen的markdown-include函数工作，因为我不懂JavaScript。

但是在我看来，你可以很容易地用Python编写一个简单的递归函数。它将以一个.md文件作为参数，并解析它，寻找表明该参数文件正在调用另一个.md文件的特征语法。解析过程不仅会寻找特征语法，还会构建一个长字符串，其中包含它沿途检查过的所有markdown内容。如果函数遇到对.md文件的引用，它会调用自身，使用刚刚找到的.md文件。当它到达底部时，它会通过递归层级返回所有经过的markdown内容。最终结果将是返回一个包含所有markdown内容的单个.md文件。

然后，将这个更大的、返回的、100%标准的markdown .md文件输入给pandoc就很容易了。

- Colin Wilder

Answer 5

这是一个用Python编写的pandoc-include过滤器的版本https://github.com/DCsunset/pandoc-include 我试过它，效果很好。它还有一些有用的选项，比如对包含的文件进行缩进和去除缩进。

- Christian Long

Answer 6

我知道这个已经很老了，但刚好碰到了。如果你需要类似的东西，可以试试用asciidoc来做文档。它在github上可以渲染基本功能，并提供像include这样的特性/语法。真的很棒，说实话，你甚至可以使用插件等等- 我最喜欢的是Mermaid用于渲染图表。你还可以选择一个处理器从你的adoc文件中输出html或pdf。

希望这对下一个遇到这个问题的人有所帮助。

- Codester