引用与参考文献
查找来源,检查其元数据,把它添加到正确的参考文献库,在光标处引用,选择 Typst 引用样式,并在不丢失原件的情况下清理文库。
引用是一条链:论述指向一个键,键指向一条参考文献条目,条目指向一个真实的来源。Oleafly 让这条链始终可见,这样一次快速查找就不会在日后变成一条莫名其妙的参考文献。

边写边引用
标题为“边写边引用”的部分
在 LaTeX 或 Typst 工具栏中选择从项目引用(@ 图标)。按键、作者或标题搜索当前参考文献库,并选择一个条目。
你也可以从 ⌘K 或 Ctrl+K 命令面板运行添加引用。Oleafly 会插入适合当前项目的语法:
- LaTeX 中是
\cite{key}; - Typst 中是
@key,如果主文档没有#bibliography(...)行,会在末尾添加一行; - Markdown 中是
[@key],需要时会在前置元数据中添加bibliography:行。
连接 Zotero 后,添加引用会先列出来自你的 Zotero 文库的匹配项。
从你的 Zotero 文库中引用
标题为“从你的 Zotero 文库中引用”的部分连接 Zotero 之后,输入 @ 以及作者姓名的一部分、标题中的一个词、年份或键。你的整个 Zotero 文库就会与项目自己的参考文献一起显示。选择一篇论文,Oleafly 会按文档已有的引用方式插入引用。LaTeX 会得到文档用得最多的命令,例如 \citep 或 \parencite,Typst 得到 @key,Markdown 得到 [@key]。在已有的 \cite{...} 内输入 @,会向其中再添加一个键。
只有那一个条目会写入项目的 .bib,放在文件末尾,文件的其余部分保持原样。已在 .bib 中的论文,无论是按它的键还是按它的 DOI,都不会被重复添加。条目从不包含你电脑上 PDF 的路径。如果项目还没有参考文献行,Oleafly 会添加一行:LaTeX 中是 \bibliography 或 \addbibresource,Typst 中是 #bibliography,Markdown 前置元数据中是 bibliography:。如果有多个 .bib 文件,Oleafly 会询问一次新参考文献放进哪个文件,并记住你的回答。
第一次在手动用 thebibliography 环境列出参考文献的 LaTeX 论文中从 Zotero 引用时,Oleafly 会提议把这份列表移入 .bib。之后所有参考文献共用同一个编号列表。
让 .bib 与 Zotero 保持同步
标题为“让 .bib 与 Zotero 保持同步”的部分如果某个被引用的键不在 .bib 中但在 Zotero 里,会提供从 Zotero 添加。从 ⌘K 面板运行从 Zotero 添加缺失的引用,可以一次检查所有被引用的键。它会添加 Zotero 中有的那些,列出没有的那些,并指出那些引用了你的参考文献中已有论文的键。
当一篇论文在 Zotero 中发生变化时,它在 .bib 中的条目会提供从 Zotero 更新。面板中的从 Zotero 更新 .bib 条目会审阅每一个发生变化的条目。你手动编辑过的条目,只有在你确认之后才会被替换。同步 Zotero 库会重新读取文库。Oleafly 绝不会自行从 .bib 中删除任何内容。

查找并添加新的参考文献
标题为“查找并添加新的参考文献”的部分从选择器中选择查找并添加新引用。可以从下面任何一种开始:
- DOI,例如
10.1145/3592979; - arXiv ID,例如
1706.03762; - ISBN-10 或 ISBN-13;
- PubMed ID(PMID);
- 包含上述某个标识符的 URL;
- 论文标题。
DOI、arXiv、ISBN 和 PubMed 查询使用它们的公开目录。标题搜索会返回可能的匹配项,附有作者、年份和发表场所,让你自己选择,而不是接受猜测。
检查返回的 BibTeX,然后选择添加到 .bib 并引用。Oleafly 会:
- 在当前参考文献库中添加一个不冲突的键;
- 当 DOI 已存在时复用已有条目;
- 在当前光标处插入引用;
- 立即刷新文件树和“参考文献”面板。
元数据是可编辑的。在它成为稿件的一部分之前,请先更正记录。
当文档声明了多个参考文献库时,对话框会显示一个参考文献菜单。条目会进入你选择的文件,Oleafly 会为该项目记住这个选择。
Oleafly 如何选择参考文献库
标题为“Oleafly 如何选择参考文献库”的部分LaTeX 项目遵循有效主文档中的声明:
biblatex使用\addbibresource{references.bib};- BibTeX 工作流使用
\bibliography{references}。
路径的解析方式,与 TeX 工具链所期望的扩展名和相对路径行为一致。指向缺失文件的声明会在其源码行处报告,而不是悄悄写到别处。
Typst 项目遵循 #bibliography(...) 调用,无论它指定的是一个文件还是一个列表,也无论文件是 BibTeX .bib 还是 Hayagriva .yml 和 .yaml。新的引用会写入文档声明的文件。如果该文件是 Hayagriva,Oleafly 会在写入之前转换 BibTeX 条目。当调用指定了多个文件时,请在对话框的参考文献菜单中选择目标。
Markdown 项目遵循前置元数据中的 bibliography: 字段。
当没有声明任何参考文献库时,Oleafly 会使用项目中的第一个 .bib。如果不存在,它会创建 references.bib,并让它出现在文件树和引用选择器中。
对于有多个库的项目,请在添加记录之前检查所选的目标。
选择 Typst 引用样式
标题为“选择 Typst 引用样式”的部分当 Typst 文档有 #bibliography(...) 调用时,“参考文献”面板的引用视图底部会显示一个引用样式菜单。它列出该项目的 Typst 版本内置的样式,以及项目中的所有 .csl 文件。选择一个样式会把它写入该调用的 style: 参数。没有设置时,Typst 使用 ieee。
对于 LaTeX,请在源码中设置样式。\bibliographystyle{ 会补全常用的 BibTeX 样式;使用 biblatex 时,请用它的 style= 选项。
导入整个参考文献库
标题为“导入整个参考文献库”的部分在“参考文献”面板中选择导入参考文献库。你可以导入文件,也可以导入你的 Zotero 文库。
从文件导入时,选择一个导出的库:
| 来源格式 | 文件 |
|---|---|
| BibTeX | .bib |
| RIS | .ris |
| EndNote XML | .xml |
| Zotero RDF | .rdf |
从 Zotero 导入时,先在设置 → 集成 → Zotero 中连接一次你的 zotero.org 账户,然后在 Zotero 卡片上选择导入 Zotero 库。Oleafly 最多导入 5,000 个条目。连接研究来源会带你完成设置。
Oleafly 会把这些记录映射为 BibTeX,并跳过 DOI 已在目标库中或已在同一批较早位置出现的参考文献。它会创建不冲突的键,并一次写入追加结果。消息会说明添加了多少条参考文献,以及已有多少条。导入文库不会在光标处插入引用。
导入之后,在引用选择器中搜索新条目,并对照原始目录核对一个样本。
清理参考文献库
标题为“清理参考文献库”的部分“参考文献”面板可以在更改文件之前预览清理结果。
- 打开项目,在“参考文献”面板中选择清理参考文献库。
- 当项目有多个
.bib文件时,选择其中一个。 - 阅读操作列表和前后对比差异。
- 检查每一项建议的键重命名、移除的 DOI 重复项和提示。
- 只有在预览符合你的意图之后才应用。
清理器会把键重命名为统一的“作者-年份-标题”模式,并更新整个项目源文件中的引用。只有当保留的条目保留了被移除条目的每个字段时,它才会移除 DOI 重复项。互相冲突的 DOI 记录和相似的标题会被标记出来供审阅,而不是凭猜测合并。
注释和 BibTeX 字符串定义会被保留。应用时会检查库是否仍与预览一致,并在更改文件之前写入备份。较大的差异在预览中显示前 500 行;应用更改时仍使用完整的文件。
补全并浏览参考文献
标题为“补全并浏览参考文献”的部分在 \cite{}、\citep{}、\citet{}、\parencite{} 和 \textcite{} 等 LaTeX 引用命令内,自动补全会搜索项目中的每个 .bib 文件。在 Typst 中,@ 会补全来自 .bib 和 Hayagriva 文件的键。连接 Zotero 后,列表中也会包括你的 Zotero 文库。
如果某条引用指向的条目是在该 .bib 未打开时添加的,例如由助手添加或来自 Zotero,它会立即解析,你不必先在文档中输入内容。
- F12 或按住修饰键点击,从引用键跳转到它的条目。
- ⇧F12 列出某个来源的所有用法。
- F2 在源文件和参考文献文件中重命名一个键。
- 悬停会显示目标;未解析或有歧义的键会在编译之前被标出。
代码智能介绍了完整的导航模型。
引用 Oleafly
标题为“引用 Oleafly”的部分如果 Oleafly 帮助了一篇论文,请从命令面板,或从“参考文献”面板引用视图的底部,运行在本文中引用 Oleafly。Oleafly 会向文档声明的参考文献库添加一个键为 oleafly 的条目,使用 BibTeX 格式,对于 Hayagriva 文件则使用 Hayagriva 格式。一条消息会指出文件和要使用的语法,例如 \cite{oleafly} 或 @oleafly,旁边有撤销。如果条目已经存在,你会收到一个关于该键的提醒。
没有参考文献文件的项目不会被更改,而是会弹出一个显示该条目的对话框供你复制。同一条目始终可以在设置 → 帮助与关于中找到。
参考文献构建与 Biber
标题为“参考文献构建与 Biber”的部分对于 biblatex,当编译器没有生成可用的 .bbl 时,Oleafly 会重新运行与之匹配的 Biber 步骤。Biber 的消息,包括缺失 .bib 路径的消息,会出现在编译日志和编辑器诊断中。
当 Biber 本身失败时,编译日志会说明原因。它会指出缺少的系统库,并建议用 \usepackage[backend=bibtex]{biblatex} 在不使用 Biber 的情况下构建。在 Fedora 上,Oleafly 的 .rpm 会推荐安装 Biber 所需的两个库。
如果参考文献仍未定义:
- 检查参考文献声明和路径。
- 打开日志,找到第一条 Biber 或参考文献消息。
- 确认该引用键恰好存在一次。
- 在
.bib文件保存后重新编译。
有关各引擎的恢复方法,请参阅编译与日志和 LaTeX 引擎与宏包。
独立的参考文献工具
标题为“独立的参考文献工具”的部分不打开项目也可以准备参考文献:
- 引用生成器接受标识符、标题、结构化字段或 BibTeX。
- 参考文献生成器构建并验证列表。
- 按样式分类的引用生成器比较八种样式。
- 专门的工具处理 DOI、ISBN、PubMed ID、arXiv 和网址。
手动编辑和引用格式化都在本地进行。标识符和标题查询需要联网。离线模式会阻止这些查询,而已有的参考文献补全和导航继续可用。
找到证据,然后核实
标题为“找到证据,然后核实”的部分查找引用会搜索学术索引,或扫描打开的草稿,找出可能需要支持的段落。引用一篇论文之前请先阅读它,并让每条论述保持在其方法和结果所能证明的范围内。