text - 如何在pandoc中为每个组成文件分别重新定义-top-level-division？

Question

我有一堆 .md 组成内容文件，标有标题 #、## 等。

我想灵活地编译新文档，组成文件保持不变，但位于最终文档的目录层次结构的不同级别。

例如:

1. 在 compiled-1.pdf 中，来自 constituent-1.md 的顶级 header # Foo 可能最终为“Chapter Foo”——其层次结构级别没有变化。

2. 但是，在 compiled-2.pdf 中，来自完全相同的 constituent-1.md 的完全相同的 # Foo可能最终会成为“Section Foo”——在 compiled-2.pdf 的 ToC 层次结构中降级为第 2 级。

在每个组成的 .md 文件中，顶级 header 始终为 # 并且每个组成的 .md 文件始终被视为不可分割的整体单元。因此，所有组成文件的 header 都将以相同的因子降级。此外，组成文件的 header 永远不会被提升。

我觉得问题与为每个文件重新设置-top-level-divison有关。如何正确执行此操作(使用 .yaml 配置和 make)？

但也许更好的方法是为每个最终文档创建一个主文件，该文件结合 include ('constituent-1.md') 等和 define ('level', '1') 等。然后，该主文件将使用 m4 进行预处理，以搜索并将 # 替换为 ## 或 ### 等，根据每个文件的 level，然后通过管道传输到 pandoc。

最好的方法是什么？

Answer 1

我认为这些是正确的想法，但不是正确的工具。您可能不想使用 m4，而是查看 pandoc filters ，尤其是内置的Lua filters或者优秀的panflute python 包。这些允许您操纵实际的文档结构而不仅仅是文本表示。

例如，这个 Lua 过滤器会降级文档中的所有 header :

function Header (header)
  header.level = header.level + 1
  return header
end

同样，您可以根据代码块定义自己的 include 语句:

```{include="FILENAME.md"}
```

包含在此过滤器中:

function CodeBlock (cb)
  if not cb.attributes.include then
    return
  end
  local fh = io.open(cb.attributes.include)
  local blocks = pandoc.read(fh:read('*a')).blocks
  f:close()
  return blocks
end

也可以仅将过滤器应用于 block 的子集(需要一些技巧):

local blocks = …
local div = pandoc.Div(blocks)
local filtered_blocks = pandoc.walk_block(div, YOUR_FILTER).content

您可以组合和扩展这些构建 block 来编写您自己的过滤器并定义您的扩展。这样，人们就可以拥有一个包含所有子文件的主文档，并根据需要改变标题级别。