如何通过CLI参数为Pandoc传递hyphenpenalty以禁用断字？

问题 #

使用Pandoc结合pdflatex将MD文件转为PDF，当前命令如下：

pandoc \
  "$md_file" \
  --pdf-engine=pdflatex \
  --variable=geometry:a4paper \
  --variable=fontsize=12pt \
  --output "${md_file%.md}.pdf"

需要通过CLI参数禁用断字，已在Markdown的YAML元数据块中添加以下内容并成功：

---
header-includes: |
  \hyphenpenalty=10000
  \exhyphenpenalty=10000
---

也已将配置提取到单独的pdf_config.yml文件，通过--metadata-file调用成功。但尝试用CLI的--metadata参数实现时出现LaTeX错误：

pandoc \
  --metadata=header-includes:hyphenpenalty=10000 \
  --metadata=header-includes:exhyphenpenalty=10000 \

错误信息：

Error producing PDF.
! LaTeX Error: Missing \begin{document}.

求正确的CLI参数传递方式。

解决方案 #

方式1：单条--metadata传递多行LaTeX代码 #

在bash中用单引号包裹完整的YAML格式内容，保留换行结构：

pandoc \
  "$md_file" \
  --pdf-engine=pdflatex \
  --variable=geometry:a4paper \
  --variable=fontsize=12pt \
  --metadata='header-includes: |
    \hyphenpenalty=10000
    \exhyphenpenalty=10000' \
  --output "${md_file%.md}.pdf"

方式2：用+追加多个header-includes元素 #

Pandoc中，--metadata=KEY+:表示向列表类型的元数据键中追加元素，同时注意给LaTeX命令添加反斜杠（bash中需转义反斜杠，或用单引号避免解析）：

pandoc \
  "$md_file" \
  --pdf-engine=pdflatex \
  --variable=geometry:a4paper \
  --variable=fontsize=12pt \
  --metadata=header-includes+:"\\hyphenpenalty=10000" \
  --metadata=header-includes+:"\\exhyphenpenalty=10000" \
  --output "${md_file%.md}.pdf"

错误原因说明 #

之前的写法存在两个核心问题：

• 缺少LaTeX命令的反斜杠，导致hyphenpenalty=10000被当成普通文本输出到文档开头，触发Missing \begin{document}错误
• 重复使用--metadata=header-includes:会覆盖之前的设置，而非追加内容到列表中

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