Pandoc忽略YAML配置选项问题求助

问题背景 #

希望通过Markdown文件的YAML头部配置替代每次复制粘贴带全参数的Pandoc CLI命令，但实际使用中多项配置未生效。

当前配置与执行结果 #

测试文件test.md内容 #

---
from: markdown
to: pdf
output-file: foo.pdf
table-of-contents: true
number-sections: true
shift-heading-level-by: -1
title:  'This is the title'
subtitle: "This is the subtitle"
author:
- Author One
- Author Two
- Author Three
---

## First header

This is the first header

## Second header

Second header with math:

$$
c^2 = a^2 + b^2
$$

执行结果 #

运行命令 pandoc test.md 后，终端直接输出HTML内容，未生成指定的foo.pdf文件。

配置生效情况分类 #

需修改键名才能生效的配置 #

• table-of-contents: true无效，改用toc: true可生效；CLI参数--table-of-contents正常有效
• number-sections: true无效，改用numbersections: true可生效；CLI参数--number-sections正常有效

始终无效的配置（CLI中可正常运行） #

• output-file
• to
• pdf-engine
• mainfont
• template: my_template.latex（本地文件）
• shift-heading-level-by: -1

正常生效的CLI命令示例 #

pandoc .\README.md -o readme.pdf --template=my_template.latex --pdf-engine=xelatex  --shift-heading-level-by=-1 

仅能正常生效的YAML配置项 #

mainfont: Segoe UI
numbersections: yes

原因分析与解决方法 #

核心参数限制 #

from（输入格式）、to（输出格式）、output-file（输出文件路径）属于Pandoc的核心执行参数，只能通过CLI指定，无法通过YAML元数据设置。这也是直接运行pandoc test.md默认输出HTML的原因——未指定输出格式和输出文件。

参数键名差异 #

部分CLI参数的YAML键名与CLI参数名不一致：

• CLI的--table-of-contents对应YAML的toc
• CLI的--number-sections对应YAML的numbersections

上下文依赖参数 #

pdf-engine、mainfont、template、shift-heading-level-by这类参数属于格式转换细节项，只有当CLI明确指定输出格式（如-t pdf）时，YAML中的对应配置才会被读取生效。

正确使用方式 #

1. CLI指定核心参数
   执行命令时必须指定输出格式和输出文件：

   pandoc test.md -t pdf -o foo.pdf
   

2. 修正YAML配置键名
   调整后的完整YAML配置：

   ---
   title:  'This is the title'
   subtitle: "This is the subtitle"
   author:
   - Author One
   - Author Two
   - Author Three
   toc: true
   numbersections: true
   shift-heading-level-by: -1
   pdf-engine: xelatex
   mainfont: Segoe UI
   template: my_template.latex
   ---
   

3. 组合命令执行
   运行以下命令即可应用所有YAML配置：

   pandoc test.md -t pdf -o foo.pdf
   

补充说明 #

使用版本为pandoc.exe 3.1.9，YAML元数据仅负责配置格式转换的细节规则，核心输入输出逻辑仍需通过CLI参数控制。

内容的提问来源于stack exchange，提问作者3dSpatialUser