Skip to main content

ZotFlow Documentation

Literature flows in, insight flows out.

ZotFlow connects Zotero and Obsidian into a single loop: your Zotero library streams into your vault, you read, annotate, and think inside Obsidian, and what you write cites back to the exact page — while every change syncs back to Zotero. Zotero stays the source of truth for your library; Obsidian is where your thinking happens.

The Loop​

ZotFlow ships a lot of features, but they all serve one of four stations:

① In — sync your library​

Connect your Zotero account and pull items, collections, attachments, and annotations into a local cache. Browse and search everything from the Tree View sidebar — fully offline once synced.

→ Installation, connecting Zotero, and first sync

② Read — annotate without leaving​

Open attachments in the built-in reader (the same engine Zotero uses, themed for Obsidian). Highlight, comment, extract annotation images. Local PDFs/EPUBs in your vault get the same treatment — their annotations stay in a sidecar file, never touching Zotero.

→ Reader & annotations

③ Distill — every source gets a page, your words get a home​

Each item renders into a Source Note: an auto-generated hub page collecting metadata, annotation excerpts, and child notes. Inside it, content has three owners — the template regenerates its part on every update; Zotero-synced regions (Item Notes, annotation comments) are editable and flow back on sync; persist regions are yours alone: local-only blocks that survive every re-render and never leave your vault. Cross-paper synthesis lives in standalone notes that link back.

→ Source Note · Item Note

④ Out — cite as you write​

Drag an item into your draft or type the trigger character to insert citations — Pandoc, wikilink, footnote, or real CSL styles rendered by citeproc. Links behave natively on both sides: they open ZotFlow's reader in Obsidian and Zotero's reader in Zotero.

→ Citation & writing flow · CSL Citations

The loop closes itself: citations from ④ jump back into ② and ③, new annotations from ② refresh ③ automatically, and everything you chose to sync returns to Zotero.

Customization & Support​

Terminology​

  • Source Note: the auto-generated Markdown hub page for a Zotero item, rendered from a LiquidJS template. The template owns its skeleton; editable regions and persist regions inside it are yours.
  • Item Note: a Zotero-native child note attached to an item — creatable, editable, and deletable from ZotFlow, synced back to Zotero. A different concept from Source Note.
  • Persist Region: a template-declared block inside a Source Note whose content is local-only — it survives every re-render and is never synced to Zotero.
  • Editable Region: a marker-fenced section of a Source Note that can be unlocked and edited. Three kinds: Item Note regions and annotation comment regions (synced), and persist regions (local-only).
  • Library Reader: the reader for Zotero library attachments; annotations sync back to Zotero.
  • Local Reader: the reader for local PDF/EPUB/HTML files in your vault; annotations live in a co-located .zf.json sidecar and never touch Zotero.