如何使用Pandoc实现Markdown转HTML时标题编号从<h2>开始且格式正常？

解决方案：使用Lua过滤器分离标题级别调整与编号逻辑 #

你遇到的问题核心在于--shift-heading-level-by=1会同时修改标题的逻辑级别（影响编号规则）和HTML输出级别，导致编号出现冗余前缀。要实现「HTML标题从

开始+常规章节编号」的需求，最稳妥的方法是用Pandoc Lua过滤器，单独调整HTML输出的标题级别，同时保留原生的章节编号逻辑。

步骤1：创建Lua过滤器文件

新建一个名为shift-heading-levels.lua的文件，写入以下代码：

function Header(el)
  -- 将所有Markdown标题的输出级别提升1级：# → <h2>，## → <h3>，以此类推
  el.level = el.level + 1
  return el
end

步骤2：执行转换命令

用以下命令转换你的Markdown文件（以示例中的abc.md为例）：

pandoc -N --section-divs --lua-filter=shift-heading-levels.lua -t html5 abc.md

验证效果

针对你提供的示例Markdown文件，转换后的简化HTML输出会是：

<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>

完全符合要求：HTML标题从

起步，章节编号是常规的1、2、1.1、2.1、2.1.1格式。

补充：添加唯一的

如果你的HTML需要包含且仅包含一个

function Header(el)
  -- 仅调整level≥2的标题，原#保留为<h1>
  if el.level >= 2 then
    el.level = el.level + 1
  end
  return el
end

开始，编号逻辑依然正常。

---

内容的提问来源于stack exchange，提问作者Masa Sakano