使用Pandoc将Markdown转Docx时，如何在目录前添加内容？

问题原因 #

你遇到的UTF-8解码错误，核心原因是**--include-before-body不能直接传入完整的docx文件**。docx本质是二进制压缩包，并非UTF-8编码的文本格式，而Pandoc对该参数的要求是：针对docx输出，要么传入纯文本/Markdown文件（Pandoc会自动转换为对应OpenXML格式），要么传入符合要求的纯文本OpenXML片段，不能直接传入完整的docx压缩文件。

正确解决方案 #

方案1：用Markdown文件做前置内容（最简单推荐） #

如果前置内容不需要特别复杂的排版，直接用Markdown文件实现：

1. 新建cover.md，写入目录前需要的内容：

# 前置章节标题
这里是目录前的具体内容，比如项目说明、封面信息等。

2. 修改Pandoc命令，将--include-before-body指向这个Markdown文件：

pandoc test.md -f markdown -t docx -s -o test.docx --reference-doc=./custom-reference.docx --number-sections=true --lof=true --toc=true --include-before-body=cover.md

生成的docx文档顺序会是：cover.md内容 → 自动生成的目录 → test.md内容，完全符合需求。

方案2：用自定义OpenXML片段实现复杂排版 #

如果需要特定字体、布局等复杂格式，可以提取docx的XML片段来实现：

1. 新建一个docx文件，只保留你要前置的内容，将文件重命名为cover.zip并解压。
2. 打开解压后word/document.xml文件，复制<w:body>和</w:body>之间的所有内容（不要包含<w:body>标签本身）。
3. 将这段内容保存为纯文本文件cover.xml，确保编码为UTF-8。
4. 执行Pandoc命令：

pandoc test.md -f markdown -t docx -s -o test.docx --reference-doc=./custom-reference.docx --number-sections=true --lof=true --toc=true --include-before-body=cover.xml

补充说明 #

--include-before-body的作用是在文档body的最开头插入内容，而Pandoc的--toc生成的目录默认会放在所有body内容的后面（即前置内容之后），刚好满足你“目录前加章节”的需求，不需要额外调整目录位置。

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