在 Obsidian 中搭建 Pandoc 引文工作流
在单个 Obsidian 笔记中引用文献,分别用 ZotLit 和原生 Pandoc 导出到 Word,并对比两份文档。
如果你想先快速浏览导出引用的简要步骤,请参阅 将带有引用的 Obsidian 笔记导出到 Word (约 5 分钟)。
本教程将引导你使用一篇笔记,分别体验 ZotLit 的内置导出和原生 Pandoc 导出。
两份 Word 文档将使用完全相同的引用和样式。最后,你可以了解这两种工作流共享了哪些部分。
开始之前
你需要:
- Obsidian 桌面版 1.15.1 或更高版本,且已安装 ZotLit。
- Zotero 9 或更高版本,导出时需保持打开。
- 在 Zotero 中安装 Better BibTeX。
- 电脑上已安装 Pandoc 3.1.1 或更高版本。
启用 Obsidian 的命令行界面(Command line interface),该功能需要 Obsidian 安装程序(installer)1.13.4 或更高版本。在原生运行期间保持 Obsidian 打开。原生 Pandoc 指南列出了完整的兼容性要求。
准备示例条目
在 Zotero 中,选择我的文库(My Library),然后选择按标识符添加条目(Add Item(s) by Identifier)。添加以下两个 DOI:
| DOI | 条目标题 | 文献引用标识 |
|---|---|---|
10.1371/journal.pmed.0020124 | Why Most Published Research Findings Are False | zotlitTutorialIoannidis2005 |
10.1126/science.aab2374 | Promoting an open research culture | zotlitTutorialNosek2015 |
打开每个条目,将其文献引用标识(Citation Key)替换为表格中的值。
在 Obsidian 中,运行 ZotLit: 打开文献笔记快速切换器。依次选择每个示例条目以创建其文献笔记。
确认 ZotLit 创建了 zotlitTutorialIoannidis2005.md 和 zotlitTutorialNosek2015.md。再创建一个名为 Reading plan 的普通 Obsidian 笔记。
在你的 Documents 目录中创建一个名为 ZotLit Pandoc tutorial 的文件夹。
配置两种引用来源
打开 设置 > ZotLit > 引文。确认 Pandoc 引用 已开启,然后开启 Wiki 链接引用。

在 参考文献 下,安装 Pandoc 引擎。该托管引擎用于排版侧边栏的 参考文献 并驱动内置导出。
打开 设置 > ZotLit 并将 APA Style 7th edition 选为 参考文献样式。其“作者-日期”格式的输出便于对比定位符(locator)和作者模式。
创建示例笔记
创建一个名为 Citation workflow check 的 Markdown 笔记,并将以下正文粘贴进去:
# Citation workflow check
A plain Literature Note link introduces the first source [[zotlitTutorialIoannidis2005]].
The same source appears with its article locator [[zotlitTutorialIoannidis2005#cite:locator=e124]].
[[zotlitTutorialIoannidis2005#cite:mode=author-in-text&locator=e124]] examines why published research findings may be false.
Nosek et al. propose guidelines for open research [[zotlitTutorialNosek2015#cite:mode=suppress-author&locator=1423]].
Both sources support the comparison [[zotlitTutorialIoannidis2005]]; [[zotlitTutorialNosek2015#cite:locator=1423]].
A literal Pandoc citation names the second source again [@zotlitTutorialNosek2015].
The wider reading list remains an ordinary vault link [[Reading plan]].保持分号和两个文献笔记链接在同一行。它们共同组成一个引文组(Citation Run)。
该笔记没有自定义的引文样式,因此它会使用你在设置中选择的 APA 样式。两次导出都会使用相同的样式。
在 Obsidian 中检查笔记
切换到实时预览,然后运行:
ZotLit: 打开参考文献侧边栏的 参考文献 显示两条记录。即使笔记多次引用了同一文献,每个来源也仅出现一次。
检查渲染后的笔记和侧边栏:
- 普通链接渲染为
(Ioannidis, 2005)。 - 带定位符的链接渲染为
(Ioannidis, 2005, p. e124)。 - 包含作者(author-in-text)的链接渲染为
Ioannidis (2005, p. e124)。 - 隐藏作者(suppress-author)的句子末尾为
Nosek et al. propose guidelines for open research (2015, p. 1423).。 - 引文组渲染为
(Ioannidis, 2005; Nosek et al., 2015, p. 1423)。 - 字面引文渲染为
(Nosek et al., 2015)。 Reading plan仍然是普通的仓库链接。

使用 ZotLit 导出
保持 Zotero 打开。
运行:
ZotLit: 导出带引文的笔记保持 格式 为 Word 文档。引文样式 显示 APA Style 7th edition,其下方的提示为 仓库设置指定了该样式。。这确认了导出会使用来自设置中的样式。
在 保存到 下,选择 选择… 并将文件保存到你的 ZotLit Pandoc tutorial 文件夹中。

选择 导出。随后的通知会指明所使用的样式,例如 已导出 Citation workflow check.docx,引文使用 APA Style 7th edition。
打开生成的 .docx 文件,重复对照侧边栏 参考文献 进行检查。
内置导出使用 Better BibTeX 从 Zotero 获取最新的参考文献数据。
保存版本匹配的集成文件对
打开 设置 > ZotLit > 引文。在 原生 Pandoc 工作流 下,找到 Pandoc 集成文件对 并选择 保存集成文件。
选择你的 ZotLit Pandoc tutorial 文件夹。ZotLit 会在该处保存 zotlit-cite.lua 和 zotlit.yaml。该文件对与你当前安装的 ZotLit 版本相匹配。每次 ZotLit 更新后,请重新保存最新的文件对。从 ZotLit 2.2.0 之前的版本保存的文件无法在 2.2.0 或更高版本中使用。
创建原生参考文献文件
在你的 ZotLit Pandoc tutorial 文件夹中保存 references.json。请确保包含示例笔记中引用的两个 Zotero 条目。
在 Zotero 中,右键点击我的文库。选择导出(Export),选择 Better CSL JSON,并勾选保持更新(Keep updated)。将文件保存为 references.json。
在源文库或分类发生更改后,Better BibTeX 会自动更新该文件。
references.json 中的文献引用标识必须与示例笔记中使用的标识一致。
运行原生 Pandoc
保持 Obsidian 打开,且当前仓库处于活动状态并已加载 ZotLit。将以下命令中的各个路径替换为绝对路径,然后在终端中运行:
pandoc "/absolute/path/to/input.md" --defaults "/absolute/path/to/workflow/zotlit.yaml" --bibliography "/absolute/path/to/references.json" --fail-if-warnings --output "/absolute/path/to/output.docx"请保留 --fail-if-warnings。当 Pandoc 在 references.json 中找不到被引条目时,它会停止运行。
Pandoc 会输出一行 ZotLit 信息,指明所使用的样式及其来源:
ZotLit: citations use APA Style 7th edition (from your vault settings).此行内容并非警告,因此运行将继续并输出 .docx 文件。
对比两份 Word 文档
将原生导出的 .docx 与内置导出的文件并排打开。两份文档应包含完全相同的两条已排版参考文献条目。内置导出会在此参考文献列表上方添加一个 References 标题,而原生导出则不会。
对比重复文献的格式、定位符、作者模式、合并的引文组、字面引文以及普通仓库链接。由于两条导出路线基于相同的笔记和样式,因此引用内容应当完全一致。
两者的参考文献数据源有所不同。内置导出向 Better BibTeX 请求最新数据,而原生 Pandoc 读取的是自动更新的 references.json 文件。
现在,你拥有了一篇既可以在 Obsidian 中预览、也可以通过任一 Pandoc 路线导出的 Markdown 笔记。
故障排除
| 现象 | 解决方法 |
|---|---|
#cite: 链接导致内置导出中断,且原生 Pandoc 针对同一个链接报错 unresolved-citation-intent | 将链接指向有效的文献笔记。如果原本只想作为普通仓库链接,请移除其 #cite: 片段。 |
| 内置导出成功,但原生 Pandoc 发出引文在参考文献中未找到的警告 | 将缺失的条目添加到 Better BibTeX 导出源中,更新 references.json,然后重新运行命令。 |
| ZotLit 更新后原生输出发生变化,或过滤器报告契约不匹配(contract mismatch) | 再次保存两个集成文件,将旧文件对一并替换。 |
有关原生错误代码的定义,请打开 设置 > ZotLit > 引文 下的 Pandoc CLI 指南。设置参考详细介绍了本地指南和集成控件。
后续步骤
最后更新于