跳到主要内容

ZotFlow 1.3.0

本次更新把真正的 CSL 引用渲染带进模板系统，为生成的 source note 提供了一块 永久属于你的书写区域，并让链接终于"入乡随俗"——在 Obsidian 里是 ZotFlow 链接，在 Zotero 里是 Zotero 链接。

升级是安全的。现有笔记与设置照常工作；所有新行为要么是可选项，要么从设计上 就不会触碰你已存储的数据。

亮点​

  • 模板内 CSL 引用 —— 新增 citation / bibliography filter，经 citeproc 按真实 CSL style 渲染，内置 style 管理器、locale 支持、 带页码定位的 annotation 引用。
  • Persist region —— 在模板中声明仅存本地的区域，内容在每次重渲染中 存活。你的阅读笔记终于可以安全地住进 source note 里。
  • 双向笔记链接 —— item note 存储原生 zotero:// 链接（在 Zotero 中由 Zotero reader 打开），在 Obsidian 中显示为 ZotFlow 链接（由 ZotFlow reader 打开）。同时识别 Zotero 7 的 zotero://open 与 Better Notes 的笔记互链。
  • 可点击的注释/引用 span —— Zotero 嵌在笔记里的高亮引文和引用标记， 现在可以直接跳转到注释位置或被引条目的 source note。
  • 本地 source note 补齐 —— 注释评论在本地笔记中也是可编辑区， persist region 同样可用。
  • 树视图可选单击打开（默认关闭）。

模板里的 CSL 引用​

两个新 Liquid filter 通过 citeproc 按真实 CSL style 渲染引用：

{{ item | citation }}                     →  (Doe, 2020)
{{ annotation | citation }}               →  (Doe, 2020, p. 5)
{{ items | bibliography: style: "apa" }}  →  完整且正确排序的参考文献表

Annotation 自动引用其父条目，页码作为规范的 CSL locator。style 在 Activity Center 管理——按 id 从官方仓库添加任意 style（带实时预览）， 自定义 .csl 文件放进指定文件夹即可，parent style 与 locale 由 ZotFlow 自动解析。

引用数据（CSL-JSON）随同步存储；旧条目首次使用时懒回填，或用 "Update CSL citation data for all items" 命令一次性全量刷新。

参数、脚注配方与已知局限见模板 Filter 参考。

Persist region：你的文字，永久保留​

source note 中可编辑区之外的一切都归模板所有、每次更新被覆写——此前你的 个人总结无处安放。现在在模板里声明一个 persist region：

## 我的总结
<!-- ZF_PERSIST_BEG_summary -->

<!-- ZF_PERSIST_END_summary -->

写在其中的内容在每次重渲染中存活，且永不同步到 Zotero。若某个区域 后来从模板中移除，其内容会被移入笔记底部边界清晰的 "Orphaned persist regions" 段——绝不删除。marker 出错时该笔记会拒绝更新，而非拿你的文字 冒险。

详见 Source Notes → Persist Region。

链接入乡随俗​

启用 Convert Item Note Links（General 设置，默认开启）后，item note 在存储与同步中保留原生 zotero:// 链接——在 Zotero 中由 Zotero reader 打开——而 Obsidian 中显示为 ZotFlow 链接，由 ZotFlow reader 打开，注释与 页码级定位均支持。无法无损转换的链接一律原样保留。

入站方向识别：zotero://select、zotero://open-pdf、Zotero 7 的 zotero://open，以及 Better Notes 的笔记互链（zotero://note/u/…）——后者直接打开对应笔记并遵循 "Always Open Child Notes in Note Editor" 设置，且往返后保持原始形态。

与该设置无关地，Zotero 嵌在笔记里的高亮引文与引用标记现在在 Obsidian 中可点击：引文跳转到 reader 中的注释位置，引用标记打开被引条目 的 source note。底层 Zotero 数据从不被修改——样式保持安静，hover 时才 显现。

本地 source note 补齐​

  • 注释评论成为可编辑区——编辑以 Zotero 评论格式回写 .zf.json sidecar，打开中的本地 reader 即时刷新。
  • Persist region 在本地笔记中同样可用。
  • 只读库不再锁定 persist region——那些内容从不离开你的 vault。

树视图：单击打开​

启用 Open Items on Single Click（默认关闭）后，箭头成为独立的展开 点击区，单击行体直接打开主目标：条目 → source note、附件 → reader、 子笔记 → 预览。

Bug 修复​

  • URL 含 & 的链接无法点击 —— markdown 转换器把链接目标里的 & 转义为 \&，而 Obsidian 点击时不做反转义。所有带查询参数的链接都受 影响，不止 Zotero 链接。已全管线修复。
  • 裸 URL 不再变形 —— 纯文本输入的 https://… 或 www.… 往返后 曾变成 <autolink> 或 [text](url) 形式，现在原样往返。
  • 带格式的高亮文本正确渲染 —— annotation.text 与评论一样可携带 Zotero 受限 HTML（<b>、<i>…），但此前只有评论被转换。现在两者在 library 与 local 模板中均正确转换（local 的评论此前完全未转换）。
  • "Copy Link" 粘贴正确转换 —— 文本与 URL 相同的 Zotero 链接是 markdown autolink，现在转换为保留 zotero:// 可见文本、点击走 ZotFlow 的规范链接。
  • 可编辑区解析器重写为精确 marker 偏移：空区域不再要求 marker 间 空行，畸形边界不可能被半转换。
  • 性能加固 —— 链接解析查询按渲染 memoize，消除两处病态正则回溯。