文内引用与文献引用标识在 Obsidian 中的工作原理
详解 ZotLit 如何解析 Obsidian 中的 Pandoc 引用与文献笔记链接,以格式化文内引用、编号参考文献并打开引用的文献。
ZotLit 使用一个有序的引用集合来排版当前笔记、对参考文献编号并支持引用跳转。
文档引用集合
文档引用集合包含当前笔记中的引用出现记录。每个引用项均保留其源码位置和引用详细信息。
设置 > ZotLit > 引文下的两项设置决定了哪些来源会纳入该集合:
| 设置 | 默认值 | 包含的来源 |
|---|---|---|
| Pandoc 引用 | 开启 | 字面 Pandoc 语法,如 @doe2024 和 [@doe2024] |
| Wiki 链接引用 | 关闭 | 符合条件的文献笔记 Wiki 链接 |
你可以同时关闭这两个来源。此时,参考文献侧边栏、格式化文内引用、数字编号以及文献引用标识跳转都将接收到一个空集合。
符合条件的 Wiki 链接未设置别名,且指向一篇文献笔记。它要么不包含片段标识,要么包含有效的引用片段(如 #cite:locator=33)。
别名、嵌入、未解析的目标、标题片段和块片段均不会纳入该集合。格式错误的引用片段同样会被排除。当开启 Wiki 链接引用 时,参考文献侧边栏会将格式错误的片段报告为参考文献错误。
该集合保留源码顺序。这一顺序至关重要,因为数字引文样式根据完整笔记来分配编号,而不是根据单一可见区域。
引用索引
引用索引是 ZotLit 内部全仓库范围的引用出现记录。它持续处于活动状态,跟踪 Pandoc 引用、文献笔记 Wiki 链接以及标注出现位置。
文档引用集合包含 Pandoc 引用和文献笔记 Wiki 链接。批注引用(无链接文本的标注链接)仅在开启 批注引用(默认关闭)时才会加入该集合。无论如何,ZotLit 都会保留标注出现记录以供标注功能使用。
当某项引用功能查询当前笔记时,文档引用集合会应用你的来源设置。更改来源设置会重新计算该集合,而无需重新扫描整个仓库。
引用插入和内置导出功能使用各自的纳入规则。关闭某个来源既不会禁用插入功能,也不会从导出中移除该来源。
Pandoc 引用
Pandoc 引用既可以引用单个作品,也可以引用一组作品:
@key是不带方括号的文内作者引用。-@key隐藏作者。[@key]和[@key, p. 3]是引用群组。[see @a, p. 3; @b]在一个群组中引用多部作品。@{https://example.com/paper}是带大括号的键,用于包含不带大括号的键无法包含的字符。
末尾的标点符号不属于文献引用标识的一部分。包含 @ 的电子邮件地址和 URL 仍保持为普通文本。
ZotLit 还会排除代码、数学公式、%% 注释、属性(frontmatter)以及 URL 中形似引用的文本。
解析机制
ZotLit 会在你的 文库范围 所涵盖的所有文库中,对照 Zotero 原生的文献引用标识字段来解析 Pandoc 引用键。它不会使用属性中的 citekey 字段进行解析。
条目即使尚未创建文献笔记,也可以作为引用出现。打开该引用将先创建文献笔记,然后再打开它。未解析的键会保持其原生源码格式,并在侧边栏中显示为参考文献错误。
解析数据会在 Zotero 数据库发生变化时自动刷新。重新生成引用标识的条目会在下一次刷新后更新。
匹配多个条目的标识
一个文献引用标识可能解析为一个 Zotero 条目、未匹配到任何条目,或匹配到多个条目。匹配到多个条目即为存在歧义的标识。当同一个文库中的两个条目具有相同的文献引用标识,或者同时纳入范围的两个文库各自包含该标识时,就会发生这种情况。
ZotLit 绝不会随意选取其中一个匹配项。编辑器、阅读视图、引用弹出框和参考文献侧边栏都会报告相同的歧义状态,并且该标识保持自身原样:它不会绑定任何候选条目,也不会生成任何参考文献条目。
在一个同时包含歧义键和未匹配键的引用群组中,该群组会优先报告未解析的键。这是因为未解析属于更严重的故障,因此会优先显示。
有两种方法可以消除歧义:在 Zotero 中为其中一个条目指定不同的文献引用标识;或者缩小你的文库范围,直到仅剩一个候选条目,使该标识重新恢复唯一性。
Wiki 链接引用
符合条件的文献笔记 Wiki 链接代表与该笔记关联的 Zotero 条目。有效的引用片段可以添加 Pandoc 详细信息,例如前缀、引文位置(locator)、后缀或隐藏作者模式。
例如,当条目的文献引用标识为 doe2020 时,[[Doe 2020#cite:locator=33]] 代表 Pandoc 源码 [@doe2020, p. 33]。
Wiki 链接会保留 Obsidian 原生的链接目标、点击行为和拖拽行为。源码模式始终显示原始的 Wiki 链接。
格式化文内引用
显示格式化引用 默认开启。 它会在实时预览和阅读视图中应用所选的
参考文献样式。源码模式始终显示 Markdown。
ZotLit 请求 Pandoc 引擎排版完整的文档引用集合。完整的渲染可确保整篇笔记中的编号和样式上下文保持一致。仅在渲染完成后,ZotLit 才会将整个文档替换为格式化文本。
在实时预览中,仅当光标位于或选中某个引用时,该引用才会恢复为 Markdown 源码。其他引用仍保持格式化状态。
当 ZotLit 无法生成完整的格式化结果时,会保持原生源码可见。
只要引用群组中包含任何未解析的条目,该群组就会完全保持原样。其中已解析的条目仍会影响后续的数字编号以及参考文献侧边栏。
批注引用仅在开启 将批注链接显示为引用(默认关闭)时才显示为格式化文本。此时它将显示为其所属条目的引用,并将标注所在页码作为引文位置。该文本来自同一次完整渲染,因此与笔记共用同一套编号。
关闭 显示格式化引用 会使每个引用来源保持 Obsidian 的原生呈现方式。这不会改变集合成员资格、文献引用标识跳转、插入或导出功能。
参考文献与错误
参考文献侧边栏为文档引用集合中的每个已解析条目展示一个条目项。格式化列表遵循所选样式的参考文献排序规则和条目标记。
如果没有格式化输出,侧边栏将使用按首次出现顺序排列的简略列表。参考文献错误会保留其精确的源码出现位置,且不会生成任何参考文献条目。
参考文献使用指南涵盖了跳转、条目操作、复制参考文献以及错误恢复。
文献引用标识跳转
将引用作为链接打开 控制字面 Pandoc 引用以及作为引用显示的文献笔记 Wiki 链接的跳转行为。它的运行独立于格式化显示和悬停行为。
单条目引用可以直接打开或创建对应的文献笔记。多条目引用则需要选择具体条目。对于存在歧义的标识,由于标识本身无法指明唯一的条目,因此需要选择具体的候选条目。
引用弹出框按引用顺序列出每个被引条目的完整参考文献条目。未解析或有歧义的标识会保持其自身状态可见,而不会关联到某个条目。
参考文献使用指南介绍了引用悬停和可用的跳转操作。命令参考列出了在光标处打开的相关命令。
主题钩子
ZotLit 仅向文档引用集合中由其提供渲染或跳转支持的来源添加公共 CSS 类。被排除的来源以及两项相关功能均未启用的来源不会获得任何公共 ZotLit 类。
有关类名、状态含义及激活规则,请参阅主题钩子。
另请参阅
最后更新于