如何在 Pandoc 交叉引用中使用 LaTeX 部分编号

Question

Pandoc documentation 表示可以通过多种方式对节标题进行交叉引用。例如，您可以创建自己的 ID 并引用该 ID。例如：

# This is my header {#header}

将创建一个可以在文本中引用的值为“#header”的 ID，如下所示：

[Link to header](#header)

这将显示文本“链接到标题”以及到标题的链接。

当编译为 LaTeX 文档时，我找不到任何地方如何使链接的文本成为节号。

例如，如果我的标题编译为“1.2.3 节标题”，我希望我对文本的交叉引用显示为“1.2.3”。

Answer 1

您可以使用pandoc-secnos 过滤器，它是pandoc-xnos 过滤器套件的一部分。

标题

# This is my header {#sec:header}

使用@sec:header 引用。或者，您可以参考

# This is my header

使用@sec:this-is-my-header。

可以通过将--filter pandoc-secnos 添加到pandoc 调用来处理以这种方式编码的Markdown 文档。 --number-sections 选项也应该使用。输出使用 LaTeX 的本机命令（即 \label 和 \ref 或 \cref）。

这种方法的好处是其他格式（html、epub、docx、...）的输出也是可能的。

Answer 2

这可以通过像之前那样定义 ID 来实现。例如：

# This is my header {#header}

那么在正文中，交叉引用可以写成：

\ref{header}

当它编译为 LaTeX 时，交叉引用文本将是引用标题的节号。

Answer 3

可以利用pandoc Lua filters 构建适用于所有支持的输出格式的通用解决方案：函数pandoc.utils.hierarchicalize 可用于获取文档层次结构。我们可以使用它来将部分 ID 与部分编号相关联，以后可以使用它来将这些编号添加到没有链接描述的链接（例如，[](#myheader)）。

local hierarchicalize = (require 'pandoc.utils').hierarchicalize

local section_numbers = {}

function populate_section_numbers (doc)
  function populate (elements)
    for _, el in pairs(elements) do
      if el.t == 'Sec' then
        section_numbers['#' .. el.attr.identifier] = table.concat(el.numbering, '.')
        populate(el.contents)
      end
    end
  end

  populate(hierarchicalize(doc.blocks))
end

function resolve_section_ref (link)
  if #link.content > 0 or link.target:sub(1, 1) ~= '#' then
    return nil
  end
  local section_number = pandoc.Str(section_numbers[link.target])
  return pandoc.Link({section_number}, link.target, link.title, link.attr)
end

return {
  {Pandoc = populate_section_numbers},
  {Link = resolve_section_ref}
}

以上内容应保存到文件中，然后通过--lua-filter 选项传递给pandoc。

示例

使用问题中的示例

# This is my header {#header}

## Some subsection

See section [](#header), especially [](#some-subsection)

使用上述过滤器，最后一行将呈现为“参见第 1 节，尤其是 1.1”。

不要忘记使用选项--number-sections 调用pandoc，否则标题不会被编号。

Answer 4

自pandoc 2.8 版起，函数pandoc.utils.hierarchicalize 已替换为make_sections。这是the @tarleb's answer 的更新版本，它适用于较新的“pandoc”版本。

local make_sections = (require 'pandoc.utils').make_sections
local section_numbers = {}

function populate_section_numbers (doc)
  function populate (elements)
    for _, el in pairs(elements) do
      if el.t == 'Div' and el.attributes.number then
        section_numbers['#' .. el.attr.identifier] = el.attributes.number
        populate(el.content)
      end
    end
  end

  populate(make_sections(true, nil, doc.blocks))
end

function resolve_section_ref (link)
  if #link.content > 0 or link.target:sub(1, 1) ~= '#' then
    return nil
  end
  local section_number = pandoc.Str(section_numbers[link.target])
  return pandoc.Link({section_number}, link.target, link.title, link.attr)
end

return {
  {Pandoc = populate_section_numbers},
  {Link = resolve_section_ref}
}