[!example] 插件名片
术语解说
| 术语 | 描述 | |
|---|---|---|
| 条目笔记（Item Note） | Zotero 中的每个文献条目下与附件同级的笔记（区别于阅读 pdf 时添加的注释，也不同于 Zotero 中与文献条目同级的笔记） 可在 ZotFlow 内创建、编辑、删除并同步回 Zotero |
|
| 文献笔记（Source Note） | ZotFlow 插件为 Zotero 的每个文献条目自动生成的 Markdown 汇总页，由 LiquidJS 模板渲染。骨架归模板所有；其中的可编辑区与 persist region 归你所有 |
|
| 可编辑区域（Editable Region） | 文献笔记中由 marker 围栏、可解锁编辑的区段。三种：条目笔记区域与批注区域（同步），以及永久保存部分（仅本地） | |
| 永久保存部分（Persist Region） | 在模板中声明的 Source Note 区块，内容仅存本地——在每次重渲染中存活，永不同步到 Zotero。 | |
| 文库阅读器（Library Reader） | 面向同步自 Zotero 文库的附件；用户在使用过程中添加的批注会被同步回 Zotero | |
| 本地阅读器（Local Reader） | 面向来自 Obsidian 库内而非同步自 Zotero 文库的 PDF/EPUB/HTML；批注存于同位置.zf.json旁车文件，永远不会被同步回 Zotero |
插件基本工作流程如图：
flowchart LR
Z[(Zotero 云端)]
I[(IndexedDB<br>本地缓存)]
SN["文献笔记<br>模板骨架<br>+ 同步区域<br>+ 永久保存部分 (仅本地)"]
M["本库笔记"]
R["阅读器<br>阅读与批注"]
Z -->|拉取| I
I -->|推送| Z
I -->|渲染| SN
SN -->|同步区域编辑| I
SN -->|引用与链接| M
M -. "跳回" .-> R
R -. "跳回" .-> M
R -->|注释变动| SN
基本用法
连接 Zotero
首先，用户应确保条目信息已经同步到 Zotero 服务器：
打开 Zotero 桌面端，在设置中的同步选项卡下登录 Zotero 账号并确认Data Syncing已启用，点击Sync按钮（绿色环形箭头）并等待同步完成
需要说明的是，对于文库的条目信息（即标题、作者、出版者等元数据），Zotero 提供官方免费同步，但附件的免费同步空间有限，此外还可通过在 Zotero 设置中的同步选项卡下配置 WebDAV 或是设置中的高级→已链接附件的根目录选项卡下配置文件夹储存附件，ZotFlow为这三种方式均提供了配置选项：
| 方案 | 详情 |
|---|---|
| Zotero 官方同步 | 内置，零配置。免费 300 MB，付费 $20/年起（2 GB），方案详见 |
| WebDAV | 自建或第三方（如 Box、pCloud、koofr）有免费档位。ZotFlow配置在 Settings → ZotFlow → WebDAV |
| 链接的文件 | PDF 放本地任意目录（或第三方云盘如 OneDrive），在 Zotero 中右键点击条目，在右键菜单中选择添加附件→链接的文件。ZotFlow在Settings → ZotFlow → General → Linked Attachment Base Directory设置基目录。仅桌面端可用 |
^85f270
在下载并启用ZotFlow插件后，
- 打开 https://www.zotero.org/settings/keys/new并登录，如不记得 Zotero 账户可在软件设置→同步下查看，网站可能会要求你创建一个快速 Pass Key，不睬它点
Maybe Later按钮进入如图界面 - 在
Key Name内给Key起一个描述名（建议就叫 ZotFlow 以方便记忆） - 在
Personal Library下，勾选Allow library access和Allow write access，后者是双向的前提 - 如需编辑 Zotero 的条目笔记，勾选
Allow notes access - 如果你使用群组功能，按需授权目标群组
- 点击
Save Key生成并复制新建 Key
回到 Obsidian 中，
- 打开
ZotFlow插件的设置并找到Sync选项卡 - 将刚刚生成的 API Key 粘贴到
API Key后的空白栏中 - 点击
Verify Key按钮，ZotFlow会校验 Key、拉取用户信息并发现所有可访问的库，如成功，字段旁将显示“Verified”字样 - Library Synchronization 表格出现，列出所有可访问的 Zotero 库
[!NOTE] 如何进行同步？
在命令面板中执行ZotFlow: Open ZotFlow Activity Center命令，打开如图所示的活动中心
在 Sync 标签页中点击想要同步的 Zotero 文库最后的Sync键，或直接点击左上方的Sync All，首次同步可能会消耗较长时间，请耐心等待
树状面板
树状面板类似于核心插件文件列表，是对导入到 Obsidian 库的文献条目的树状总览
右击条目可执行如图操作：
右击分类可执行如图操作：
活动中心
在命令面板中执行ZotFlow: Open ZotFlow Activity Center命令即可唤出活动中心
- Sync 标签页：触发全量或单库同步，解决同步冲突
- Tasks 标签页： 监控当前/队列中任务进度
- Template 标签页：LiquidJS 模板沙箱，实时预览渲染结果
- CSL 标签页：管理
citation/bibliographyshai x筛选器使用的引用样式：按 id 添加（带实时预览）、自定义.csl文件夹、一键更新 - Repair 标签页：修复因重渲染产生的失效块引用
- Telemetry 标签页：按级别过滤的运行日志
阅读器
ZotFlow的内置阅读器使用了与 Zotero 相同的 PDF/EPUB/HTML 渲染引擎，分：
- 文库阅读器（Library Reader）：面向同步自 Zotero 文库的附件；用户在使用过程中添加的批注会被同步回 Zotero
- 本地阅读器（Local Reader）：在插件设置中启用
General → Overwrite PDF/EPUB/HTML Viewer选项后重启 Obsidian 即可启用，面向来自 Obsidian 库内而非同步自 Zotero 文库的 PDF/EPUB/HTML；批注存于同位置.zf.json旁车文件，永远不会被同步回 Zotero
[!NOTE] 如何打开附件？
- 在命令面板中执行
ZotFlow: Open Zotero Tree View命令，打开侧边栏树状面板，在其中找到想要打开的附件双击- 在命令面板中执行
ZotFlow: Search Zotero Library命令，打开搜索面板，输入关键词后找到想要打开的附件单击- 可从外部或笔记内通过 URI 跳转到附件、批注或文献笔记：
URI 类型 格式 打开附件 obsidian://zotflow?type=open-attachment&libraryID=<id>&key=<key>打开批注 obsidian://zotflow?type=open-annotation&libraryID=<id>&key=<key>打开文献笔记 obsidian://zotflow?type=open-note&libraryID=<id>&key=<key>
[!NOTE] 可以添加哪些类型的批注？
如上图，在阅读器界面上方的批注工具栏中，按钮从左到右依次为高亮文本、下划线文本、笔迹注释、新增文字、选择区域和绘图，与 Zotero 自带工具一致，详细说明见下方表格和图例
批注类型 说明 高亮文本 选中文本并应用彩色高亮 下划线文本 选中文本并应用彩色下划线 笔记注释 在页面任意位置放置 sticky note 新增文字 在页面任意位置添加无边框文本框输入文本 选择区域 在文献中截取形状为矩形的图 绘图 自由手写/手绘
在完成一次阅读后建议在命令面板中执行ZotFlow: Sync libraries命令将批注同步到 Zotero
[!NOTE] 如何提取批注图片？
插件可将选择区域和绘图类型的批注可保存为.png文件
在插件设置中启用General → Auto Import Annotation Images选项并在Annotation Image Folder选项中指定存放文件夹，当文献笔记创建或更新时，会自动将批注中的图片导出到指定文件夹
也可在树状视图中右键点击条目执行Extract annotation images命令
文献笔记
文献笔记是Zotflow的核心机制，它是文献条目在 Obsidian 库中的汇总页 ，储存了文献的元数据、批注等信息
[!NOTE] 从 Zotero 条目创建或更新文献笔记流程图
flowchart LR A[读取存放路径模板<br/>决定存放位置] --> B[读取内容模板] B --> C[从本地 IndexedDB 收集<br/>条目元数据、条目笔记、附件和批注信息] C --> D[LiquidJS 渲染模板<br/>产出 Markdown 正文] D --> E{目标文件<br/>是否已存在？} E -- 是 --> F[在笔记属性中保留用户手动添加的属性<br/>仅在笔记缺失模板中含有 ?? 前缀时用模板填充<br/>无 ?? 前缀的字段始终被模板覆盖] E -- 否 --> G[直接应用渲染结果] F --> H[添加如下强制字段<br/>zotflow-locked: true<br/>library-id<br/>zotero-key<br/>item-version] G --> H H --> I[生成最终 Markdown 文件]
- 从本地文件生成文献笔记的流程基本相同，仅上下文变量和强制字段有所不同：
zotflow-locked: true和zotflow-local-attachment: [[path/to/file.pdf]] - 本地文件的批注数据存储在该文件同位置的
.zf.json中（如Papers/paper.pdf→Papers/paper.zf.json），不在文献笔记内部
[!NOTE] 文献笔记分哪几个部分？
- 笔记属性分两种
- 模板中定义的属性，在模板的笔记属性区声明，更新时，仅在笔记缺失模板中含有
??前缀时用模板填充，无??前缀的字段始终被模板覆盖，强制字段zotflow-locked: true、zotero-key、item-version、library-id和zotflow-local-attachment始终由系统输入- 用户在文献笔记中手动添加的属性
- 正文分三个部分，由隐藏的 HTML 评论标记符包裹，视为可编辑区
- 条目笔记：是文献在 Zotero 内的条目笔记经由 Markdown 渲染后的样子，由
<!-- ZF_NOTE_BEG_<key> --> … <!-- ZF_NOTE_END_<key> -->包裹- 批注：是在插件或 Zotero 阅读器中为文献附件某部分添加的批注，由
<!-- ZF_ANNO_BEG_<key> --> … <!-- ZF_ANNO_END_<key> -->包裹- 永久保存部分：永远仅存在本地，供用户自由发挥的区域，由
<!-- ZF_PERSIST_BEG_<id> --> … <!-- ZF_PERSIST_END_<id> -->包裹
在编辑模式下，以上任一部分会在标识符行首显示图标，点击解锁后即可编辑
保存时，条目笔记部分会由 Markdown 转写回 Zotero HTML 语法，更新 IndexedDB 中的对应记录。如果该部分包含<!-- ZF_NOTE_META … -->行，wrapper 属性会在回写时重建；批注部分去除>前缀，由Markdown 转回 Zotero 批注 HTML 语法（仅支持<b>、<i>、<sub>、<sup>），更新 IndexedDB 中对应数据
由于条目笔记在同步回 Zotero 时会转换格式，笔者建议不写条目笔记，而是在永久保存部分中撰写总结或阅读笔记，如仍欲在 Zotero 中使用条目笔记，请见插件作者撰写的文档和Markdown 语法支持 | ZotFlow笔者不加赘述了（可以狠狠偷懒）
引用与写作
[!NOTE] 引用格式有哪几种？
格式 示例输出 说明 Pandoc [@smith2024, pp. 3, 7]Pandoc 风格 citation key + 方括号。自动附加批注页码 脚注 [^smith2024]+ 文档末尾的定义Markdown 脚注。行内插入引用标记，定义文本追加到文档末尾 Wikilink [[Source/@smith2024|Smith (2024)]]指向文献笔记的 Wikilink，有批注时指向具体被批注段落 Citekey @smith2024裸 citation key——不经模板处理，直接输出
[!NOTE] 如何插入批注？
操作 Zotero 附件 本库文件 在树状面板中拖拽任意非笔记条目到编辑器中 插件设置中默认的引注格式 不适用（本地文件不在树状面板中） 在编辑器中输入自定义触发词，在弹窗中输入关键词筛选文献 在阅读器内选中批注后按 Ctrl+C插件设置中默认的引注格式 块引用链接 (``) 在阅读器内选中批注后按 Ctrl+Shift+C批注原始文本 批注原始文本 阅读器右击批注唤出右键菜单 复制嵌入部分、被高亮文本、默认引注格式、Pandoc、脚注和 Wikilink 引用 仅 embed + text 在拖拽时按住以下按键可进行其它形式的快捷引用：
修饰键 格式 Shift Wikilink Alt Pandoc Ctrl / Cmd 脚注 Ctrl+Shift / Cmd+Shift Citekey（裸 key）
[!NOTE] Title
如在阅读器中选中多条批注并进行引用时，默认模板的处理如下：
- Pandoc：去重拼接页码 →
[@smith2024, pp. 3, 7, 12]- Wikilink：为每条批注生成独立
[[note#^id|Author (year), p. X]]，以逗号分隔- 脚注：默认模板不使用批注数据（但可自定义）
将批注嵌入正文时，会生成指向文献笔记对应批注的块引用，例：``，如存在多条批注，每条单列一行
CSL
在插件设置→CSL Render→中设置完Default Style和Default Outpu Format后，在任意文献笔记或引注模板中应用如下筛选器，然后批注便会自动生成规范引注：
{{ item | citation }}
{{ item | citation: "ieee" }} {%- comment %} 单次调用覆盖 style {% endcomment %}
[!NOTE] 如何管理样式？
点击右上角加号，在弹窗中输入从Zotero 官方样式仓库中复制的 ID 或样式链接即可添加样式
打开活动中心，在CSL标签页中
也可自行下载.csl样式文件，将其放入插件设置指定的文件夹中
模板
ZotFlow共用LiquidJS作为模板引擎 ，语法兼容 Shopify Liquid，在设置中留空则使用内置模板
| 模板类型 | 控制内容 | 设置位置 |
|---|---|---|
| 条目笔记 | Zotero 文库内的条目笔记 | General → Template Path |
| 文献笔记 | Obsidian库内文献笔记的正文 | General → Local Source Note Template |
| 引注 | Pandoc、Wikilink、脚注和 Citekey 引用格式的输出 | Citation |
| 路径 | 文献笔记的存放位置 | General → Note Path Template → Local Source Note Path Template |
每种模板均有自身的特有变量，详见插件文档的模板变量与默认模板部分
详见插件文档的模板筛选器参考部分
[!NOTE] LiquidJS 速查表
模板由以下元素构成：
功能 语法 说明 输出标签 {{ variable }}插入变量值 逻辑标签 {% if condition %} ... {% endif %}条件分支 循环 {% for item in array %} ... {% endfor %}遍历数组 过滤器 {{ value | filter_name }}值变换（如 | json、| default: "fallback"、| slice: 0, 4）空白控制 {%-和-%}修剪前后空白，避免输出多余换行 变量捕获 {% capture var %}...{% endcapture %}将一段内容赋值给变量 全局可用变量： newline，类型为字符串，字面换行符 为"\n"，用于replace过滤器处理多行文本
[!NOTE] 笔记属性渲染与合并策略是什么样的？
flowchart LR A[解析模板] --> B[分离笔记属性和正文] B --> C[渲染笔记属性] C --> E{目标文件是否已经存在？} E -- 是 --> F[合并字段<br>?? 前缀字段仅在 note 无此字段时填充<br>无 ?? 前缀字段直接覆盖] E -- 否 --> G[直接应用模板] F --> H[注入强制字段] G --> H H --> I[序列化为 YAML 字符串] B --> J[渲染正文] I --> K[组合笔记属性和正文] J --> K K --> L[最终 Markdown 文件]
[!NOTE] 如何在不新建文件的情况下预览模板？
唤出活动中心，切换至 Template 标签页→选择欲预览的模板类型和文献条目，点击右下方Render按钮后即可查看效果，右上方可在源码模式和阅读模式之前切换
关于模板的写法示例，可见插件文档模板指南中的常见写法与技巧部分
关于模板的筛选器写法示例，可见插件文档的有关部分
设置说明
GeneralLibrary Source Note：本选项部分针对的是来自 Zotero 文库的条目的文献笔记Template path：在空白栏中填入的基于库目录的相对文件夹路径将被视为文献笔记模板的默认存放路径Library Source Note Path Template：在空白栏中以 LiquidJS 语法写成的文件夹路径将被视为文献笔记的存放路径模板Convert Item Note Links：如启用，则在文献笔记内将链接渲染为 Zotflow 链接，但同步回 Zotero 时则还原为 Zotero 链接Lock Editable Region by Default：如启用，则文献笔记的可编辑部分Hide Editable Region Markers：如启用，则ZF_NOTE和ZF_PERSIST不会在文献笔记中显示，但区域的分隔符依然会显示Always Open Child Notes in Note Editor：
Local Source Note：本选项部分针对的是来自 Obsidian 库内附件的文献笔记Source Note Template Path：在空白栏中填入的基于库目录的相对文件夹路径将被视为文献笔记模板的默认存放路径Local Source Note Path Template：在空白栏中以 LiquidJS 语法写成的文件夹路径将被视为文献笔记的存放路径模板Annotation Sidecar Folder：在空白栏中填入的基于库目录的相对文件夹路径将被视为本地阅读器的批注的存放位置，留空时默认储存在附件旁边
Linked AttachmentsLinked Attachments Base Directory：如果用户在 Zotero 中使用了[[#^85f270|链接的文件]]，则应在此处填入对应文件夹的绝对路径
General SettingsOpen items on single click：如启用，则单击即可打开文献笔记、附件或笔记预览；反之则双击打开，单击仅执行展开/收起动作Auto Import Annotation Images：如启用，则创建文献笔记时，自动从文献笔记 PDF 中导入绘图/选择区域批注的图片Annotation Image Folder：在空白栏中填入的基于库目录的相对文件夹路径将被视为上一选项中导入的图片的默认存放位置
Zotero ReaderOverwrite PDF/EPUB/HTML Viewer：如启用，则用插件内置阅读器代替系统阅读器在 Obsidian 中打开 PDF/EPUB/HTML 格式文件Turn Off note, text, and image annotation tools after each use：如启用，则每次完成批注后，会自动从对应批注工具切换回鼠标Ebook Font：在空白栏中填入的字体名将被视为阅读器的默认字体，如留空则使用附件的内置字体Reader UI Color Scheme：在下拉菜单中选择阅读器 UI 的配色方案Default Viewer Light Theme：在下拉菜单中选择阅读器在亮色模式下的主题Default Viewer Dark Theme：在下拉菜单中选择阅读器在暗色模式下的主题
SyncAPI Key：在空白栏中填入 Zotero API 密钥以连接用户 Zotero 账号下数据，点击Verify按钮验证可用性Auto-update source notes after sync：如启用，则在同步时，如文献笔记所对应的 Zotero 文献条目发生了变化，会自动刷新文献笔记中的数据，此处为增量更新，仅修改发生了变化的条目Auto-purge source notes for trashed items：如启用，则在同步时，如文献笔记所对应的 Zotero 文献条目被删除，会自动删除该文献笔记Library Syndication：在下拉菜单中为每个文库设置相应的同步策略：Bidirectional：拉取 + 回写（推荐用于个人主库）Read only：仅拉取（适合共享组库、审阅场景）Ignored：同步时跳过
WebDAV
-Enable WebDAV Sync：如启用，则将从用户指定的 WebDAV 而非 Zotero 服务器同步附件
-Server URL：必须包含/zotero，直接指向 Zotero 存放附件的那个zotero文件夹。这与 Zotero 客户端里的填法不同：Zotero 会自动在你填的地址后面补上zotero/，而 ZotFlow 不会，所以要自己带上。比方说 Zotero 里配置的是https://dav.example.com/dav，这里就填https://dav.example.com/dav/zotero
-Username：WebDAV 的用户名
-Passward：WebDAV 的密码CacheAttachment CacheEnabling Caching：如启用，则会缓存已经下载的附件以加快打开速度Max Cache Limit（MB）：空白栏中填入的数字将被视为用户允许的最大缓存占用量，留白或填 0 则视为不限制，点击Purge Cache可清除所有缓存
CitationDefault Citation Formula：在下拉菜单中选择默认引用格式Trigger Character：空白栏中填入的符号将被视为编辑器正文中触发自动建议的符号Pandoc Template：在空白栏中以 LiquidJS 语法写成的 Pandoc 引注模板，留空则使用默认的[@citekey]Footnote Reference Template：在空白栏中以 LiquidJS 语法写成的行内脚注引注模板，留空则使用默认的[^item.citationkey]Footnote Definition Template：在空白栏中以 LiquidJS 语法写成的尾注引注模板，留空则只应用行内脚注引注模板Wikilink Template：在空白栏中以 LiquidJS 语法写成的 Wikilink 模板，留空则使用 Obsidian 的自带格式Auto-copy New Annotation：在下拉菜单中选择在阅读器中新建批注时，是否要复制它：Embed：写入剪贴板的是带有块 ID 可以直接插入的块引用Text：写入剪贴板的是被高亮的文本Citaion：写入剪贴板的是以默认引注格式格式化以后的文本
CSL RenderRenderingDefault Style：在下拉菜单中选择默认引注风格Default Output Formula：在下拉菜单中选择默认的输出格式
Custom StylesCustom Styles Folder：在空白栏中填入的文件夹名称将被视为自定义样式的存放文件夹
CacheClear Cache：点击Clear Cache按钮以清除所有用户下载的样式文件