指定从<h2>开始的Pandoc编号

Question

我希望从<h2>开始，将带有头编号的标记转换为HTML。实现这一目标的方法是什么？

pandoc提供了选项--number-sections (或-N)，以便在输出中对头进行编号。现在，我正尝试使用此选项将标记转换为HTML。

默认情况下，pandoc的输出header级别从<h1>开始。它并不理想，所以我想将它更改为<h2> (虽然最初的标记可能包含许多第一级标题，但是输出<h1>最多应该包含1 <h1>)。

可以指定--shift-heading-level-by=1；然后，输出头级别从<h2>开始(参见官方的Pandoc用户指南，也可能是这个问题)。然而，它会搞乱节-编号！基本上，区段编号的级别也在发生变化。现在所有的部分都在"0“下面(比如0.1，0.2，0.2.1，…)一节也不存在。

pandoc提供了另一个选项--number-offset=1，但它所做的只是抵消"0.1"→"1.1“这样的数字。然后，所有的区段数都从1开始，没有编号为2。显然，这是没有意义的。前缀号“1”。是多余的，应该从所有节号(如1.1→1、1.1.4→1.4、1.2.3→2.3等)中删除。

为了演示起见，下面是一个示例标记文本文件(abc.md)

%Test-md

# First Header (1) #

## Header (1-1) ##

# Second Header (2) #

## Header (2-2) ##

### Header (2-3) ###

及其输出的HTML (简化)

pandoc -N --section-divs --shift-heading-level-by=1 -t html5 abc.md

<section id="first-header-1" data-number="0.1">
  <h2 data-number="0.1">0.1 First Header (1)</h2>
    <section id="header-1-1" data-number="0.1.1">
      <h3 data-number="0.1.1">0.1.1 Header (1-1)</h3>
    </section>
  </section>
  <section id="second-header-2" data-number="0.2">
    <h2 data-number="0.2">0.2 Second Header (2)</h2>
      <section id="header-2-2" data-number="0.2.1">
        <h3 data-number="0.2.1">0.2.1 Header (2-2)</h3>
        <section id="header-2-3" data-number="0.2.1.1">
          <h4 data-number="0.2.1.1">0.2.1.1 Header (2-3)</h4>
       </section>
  </section>
</section>

如何使pandoc以普通的方式(1、2、2.1、2.2、2.2.1)进行编号，然后从<h2>开始输出头部级别的HTML

Answer 1

Pandoc首先移动标题，然后进行编号。不过，这不是我们想要的，我们希望这个数字能先发生。可以使用pandoc Lua滤波器来控制这一点。

函数pandoc.utils.make_sections执行通过在命令行上传递--section-divs或--number-sections而触发的操作。通过手动修改所有--shift-heading-level-by=1元素，可以匹配Header的效果：

function Pandoc (doc)
  -- Create and number sections. Setting the first parameter to
  -- `true` ensures that headings are numbered.
  doc.blocks = pandoc.utils.make_sections(true, nil, doc.blocks)

  -- Shift the heading levels by 1
  doc.blocks = doc.blocks:walk {
    Header = function (h)
      h.level = h.level + 1
      return h
    end
  }

  -- Return the modified document
  return doc
end

过滤器将通过将其保存到文件shifted-numbered-headings.lua来使用。然后可以通过--lua-filter/-L参数将其传递给pandoc。仍然必须传递--number-sections/-N选项才能使编号变得可见，--section-divs仍然是获取<section>元素的必要条件。

pandoc \
    --lua-filter=shifted-numbered-headings.lua \
    --number-sections \
    --section-divs \
    ...

pandoc在<section>元素上设置的<section>将始终反映实际的标记级别:包装<h2>标题的<section>将具有class="level2"，即使在概念上它是第一级标题。这可能令人困惑，不幸的是，不能用过滤器进行更改。

Answer 2

到目前为止，我找到的最简单的解决方案是分两步完成。首先，将标记转换为HTML，而不改变头级别。然后，将HTML转换为另一个HTML，其中头部级别被1移动：<h1>→<h2>。

下面是一个示例代码：

pandoc -N --section-divs -t html5 /tmp/try1.md |\
  pandoc --from=html -t html5 --shift-heading-level-by=1 > output.html

注意第二个pandoc中的pandoc --这是必要的，因为否则pandoc将不知道流(管道)输入的文件类型。

这是(简化的)输出。现在没有像“0”这样的冗余公共前缀。或"1.“在页眉编号中。

<section id="first-header-1" data-number="1">
  <h2 data-number="1">1 First Header (1)</h2>
    <section id="header-1-1" data-number="1.1">
      <h3 data-number="1.1">1.1 Header (1-1)</h3>
    </section>
</section>
<section id="second-header-2" data-number="2">
  <h2 data-number="2">2 Second Header (2)</h2>
    <section id="header-2-2" data-number="2.1">
      <h3 data-number="2.1">2.1 Header (2-2)</h3>
        <section id="header-2-3" data-number="2.1.1">
          <h4 data-number="2.1.1">2.1.1 Header (2-3)</h4>
        </section>
    </section>
</section>

请注意，number-offset是不相关的，因为它指定从默认的1或0的不同数字开始的编号，并且不对节编号级别执行任何操作。