使用Pandoc将md转docx时无法调用custom-reference.docx的问题

问题场景 #

尝试使用Pandoc将Markdown转换为docx时，已按照手册将自定义参考文档custom-reference.docx放置在用户数据目录/home/jonathan/.pandoc，但执行转换命令时始终提示文件不存在。相关操作与环境信息如下：

测试文档（test.md） #

---
title: Minimal Working Example
author: test
---

## This is a test

I am trying to get a custom reference doc to work, but I'm having trouble.
Here is a minimal working example.

Pandoc版本信息 #

$ pandoc --version
pandoc 2.17.1.1
Compiled with pandoc-types 1.22.2.1, texmath 0.12.4, skylighting 0.12.3.1,
citeproc 0.6.0.1, ipynb 0.2
User data directory: /home/jonathan/.pandoc
Copyright (C) 2006-2022 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

目录文件确认 #

$ ls /home/jonathan/.pandoc
custom-reference.docx

错误命令与提示 #

$ pandoc --reference-doc=custom-reference -o test.docx test.md
pandoc: custom-reference: openBinaryFile: does not exist (No such file or directory)

已尝试--reference-doc=custom-reference.docx和--reference-doc=/home/jonathan/.pandoc/custom-reference命令，均未解决问题。

解决步骤 #

1. 确保指定完整文件名后缀 #

Pandoc查找参考文档时，必须指定完整的.docx后缀，无论使用相对名还是全路径：

• 依赖用户数据目录的相对名命令：

  pandoc --reference-doc=custom-reference.docx -o test.docx test.md
  

• 全路径命令：

  pandoc --reference-doc=/home/jonathan/.pandoc/custom-reference.docx -o test.docx test.md
  

2. 检查文件权限 #

确认Pandoc具备读取该参考文档的权限：

ls -l /home/jonathan/.pandoc/custom-reference.docx

确保文件所有者为当前用户，且拥有读权限（权限位包含r，例如-rw-r--r--）。若权限不足，执行以下命令修正：

chmod 644 /home/jonathan/.pandoc/custom-reference.docx

3. 验证Pandoc的文件查找路径 #

通过--verbose参数查看Pandoc实际的文件查找过程，确认是否在正确的目录下搜索：

pandoc --verbose --reference-doc=custom-reference.docx -o test.docx test.md

在输出日志中查找类似Looking for custom-reference.docx in data directories的条目，确认路径是否与/home/jonathan/.pandoc一致。

4. 重新生成标准参考模板 #

确保自定义参考文档是基于Pandoc官方模板修改的，而非任意docx文件。执行以下命令生成标准模板，再修改后替换原文件：

pandoc -o /home/jonathan/.pandoc/custom-reference.docx --print-default-data-file reference.docx

修改该模板的样式后，再次尝试转换命令。

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