Skip to main content

ZotFlow 1.3.0

This release brings real CSL citation rendering into your templates, gives you a permanent place for your own words inside generated source notes, and makes links finally behave like they belong to whichever app you're in — ZotFlow links here, Zotero links there.

Updating is safe. Existing notes and settings keep working; all new behaviors are either opt-in or designed to never touch your stored data.

Highlights​

  • CSL citations in templates — new citation / bibliography filters render real CSL styles via citeproc, with a built-in style manager, locale support, and page-aware annotation citations.
  • Persist regions — declare local-only blocks in your source note template that survive every re-render. Your reading notes finally live inside the source note, safely.
  • Two-way note links — item notes store native zotero:// links (open in Zotero's reader there) but display ZotFlow links in Obsidian (open in ZotFlow's reader here). Zotero 7's zotero://open and Better Notes' note-to-note links are understood too.
  • Clickable annotation & citation spans — the highlight quotes and citation markers Zotero embeds in notes now jump to the annotation or the cited item's source note.
  • Local source notes catch up — annotation comments are now editable regions in local notes, and persist regions work there as well.
  • Optional single-click open in the tree (off by default).

CSL citations in your templates​

Two new Liquid filters render citations with citeproc using real CSL styles:

{{ item | citation }}                     →  (Doe, 2020)
{{ annotation | citation }}               →  (Doe, 2020, p. 5)
{{ items | bibliography: style: "apa" }}  →  a full, correctly sorted bibliography

Annotations cite their parent item automatically, with the page label as a proper CSL locator. Styles are managed from the Activity Center — add any style from the official repository by id (with live preview), drop custom .csl files into a folder, and ZotFlow resolves parent styles and locales for you.

Citation data (CSL-JSON) is stored during sync; older items are backfilled lazily on first use, or all at once via the "Update CSL citation data for all items" command.

See Template Filters for parameters, footnote recipes, and known limitations.

Persist regions: your words, kept​

Everything outside editable regions in a source note is template-owned and overwritten on every update — until now there was nowhere to keep your own summary. Declare a persist region in your template:

## My Summary
<!-- ZF_PERSIST_BEG_summary -->

<!-- ZF_PERSIST_END_summary -->

Whatever you write inside survives every re-render and is never synced to Zotero. If a region is later removed from the template, its content is moved to a clearly-bounded "Orphaned persist regions" section at the bottom of the note — never deleted. Marker problems make the note refuse to update rather than risk your text.

Details in Source Notes → Persist Regions.

With Convert Item Note Links (General settings, on by default), item notes keep native zotero:// links in storage and sync — so in Zotero they open Zotero's reader — while Obsidian displays them as ZotFlow links that open ZotFlow's reader, including annotation and page-level targets. Anything that can't be converted losslessly is left untouched.

Understood on the way in: zotero://select, zotero://open-pdf, Zotero 7's zotero://open, and Better Notes note-to-note links (zotero://note/u/…), which open the note itself and honor your "Always Open Child Notes in Note Editor" preference — Better Notes links survive the round trip in their original form.

Independently of that setting, the annotation highlights and citation markers Zotero embeds in notes are now clickable in Obsidian: quotes jump to the annotation in the reader, citation markers open the cited item's source note. The underlying Zotero data is never modified — styling stays quiet until you hover.

Local source notes catch up​

  • Annotation comments are editable regions in local source notes too — edits write back to the .zf.json sidecar in Zotero's comment format, and an open local reader picks them up immediately.
  • Persist regions work in local notes.
  • Read-only libraries no longer lock persist regions — that content never leaves your vault.

Tree view: open on single click​

With Open Items on Single Click (off by default), the chevron becomes its own click zone for expanding, and clicking a row opens its primary target directly: source note for items, reader for attachments, preview for child notes.

Bug fixes​

  • Links with & in the URL were unclickable — the markdown converter escaped & as \& in every link destination, and Obsidian doesn't unescape on click. This affected all links with query parameters rendered from notes, not just Zotero ones. Fixed across the pipeline.
  • Bare URLs no longer mutate — a plain https://… or www.… typed as text used to come back from a round trip wrapped as <autolink> or [text](url). Plain URLs now round-trip verbatim.
  • Formatted highlight text renders correctly — annotation.text can carry Zotero's restricted HTML (<b>, <i>, …) just like comments, but only comments were converted to markdown. Both are now, in library and local templates alike (local comments were never converted at all).
  • "Copy Link" pastes convert cleanly — Zotero links whose visible text equals the URL are markdown autolinks; they now convert into a proper link that keeps the familiar zotero:// text while opening in ZotFlow.
  • Editable-region parser rewritten on precise marker offsets: empty regions no longer require a blank line between markers, and malformed edge cases can't be half-converted.
  • Performance hardening — link-resolution queries are memoized per render, and two pathological regex backtracking cases were eliminated.