Item Note: Zotero Child Notes
An Item Note is a child note item under a Zotero entry — Zotero's native note object. ZotFlow treats it as a first-class editable object: you can create, edit, and delete entirely within Obsidian, with changes written back to Zotero on the next bidirectional sync.
Distinction from Source Note (Avoiding Confusion)
Important clarification: the word "note" refers to two completely different concepts in ZotFlow:
| Concept | What it is | Storage |
|---|---|---|
| Source Note (Obsidian) | Auto-generated Markdown file from a template, one per Zotero item | .md file in your vault |
| Item Note (Zotero, the subject of this page) | Zotero native child note item, attached to a parent entry | IndexedDB → pushed to Zotero via bidirectional sync |
This page covers only Item Notes. For Source Notes, see Source Note.
Item Note or Persist Region?
Both hold your thoughts about a single source — the deciding question is whether Zotero should see them:
- Item Note — syncs back to Zotero: readable in Zotero's UI, on every device Zotero reaches, and survives independently of your vault. Use it for content that belongs to the reference, not just your vault.
- Persist region — local-only, lives inside the Source Note itself, never synced. Use it for private reading notes, verdicts, or workflow scratch that Zotero has no business seeing.
See the ownership model for the full decision table.
Where Item Notes Appear
In the Zotero Tree View, child notes appear as 📝 leaf nodes under their parent item:
📚 My Library
└── 📄 Smith et al. (2024) — Distributed Tracing
├── 📎 smith2024.pdf
├── 📝 Open questions
└── 📝 Summary
Inside the Source Note body, each child note is rendered by default within its own editable region, wrapped by <!-- ZF_NOTE_BEG_<key> --> / <!-- ZF_NOTE_END_<key> --> markers (see Editable Regions).
Creating an Item Note
Three entry points — all guarded by library write permission:
From the Zotero Tree View:
- Right-click a parent item (any item that is not a standalone attachment)
- Select Create child note
From an open Source Note (both act on the note's item):
- Command palette →
ZotFlow: Create child note for current source note - The tab's three-dot menu (top-right) → ZotFlow: Create child note
Every entry point then proceeds identically — ZotFlow will:
- Create an empty note in IndexedDB with
syncStatus: "created" - Refresh the Tree View — a new
📝node appears - Open the Note Editor in a new tab, ready for input
At this point the note's key is temporary. On the next bidirectional sync, Zotero assigns the real key, and ZotFlow automatically updates the local record. Until then, the note is fully functional locally.
Entry points are hidden or refused when:
- The target is a standalone attachment (attachments cannot have child notes)
- The library mode is Read Only
- The API Key lacks notes write permission
Opening a Child Note
There are three ways to open a child note, controlled by the Always Open Child Notes in Note Editor setting (Settings → ZotFlow → General):
| Setting | Behavior |
|---|---|
| Off (default) | Child notes open in their parent's source note, scrolled to the note's editable region |
| On | Child notes always open in the standalone Note Editor view |
Regardless of the setting, you can bypass the default behavior via the Tree View context menu:
- Right-click a
📝node → Locate in Source Note — Opens the parent source note scrolled to the note's editable region (even when the setting is on). - Right-click a
📝node → Open in Note Editor (Experimental) — Opens the note directly in the standalone Note Editor view (even when the setting is off).
Editing an Item Note
There are two equivalent editing entry points. Both write to the same IndexedDB record and produce the same outgoing sync — choose by context.
Method 1: Note Editor (Standalone Tab Editor)
Open via:
- Double-click a
📝node in Tree View, or - Right-click → Open note (appears in applicable contexts), or
- Right-click → Open in Note Editor (Experimental), or
- URI:
obsidian://zotflow?type=open-item-note&libraryID=<id>&key=<key>(routes per the Always Open Child Notes in Note Editor setting;type=open-noteopens an item's Source Note instead)
The editor is Obsidian's standard embeddable Markdown editor — your shortcuts, snippets, CSS, and other plugin behaviors all work normally. On top of this, ZotFlow:
- Loads the note's Zotero HTML, converts to Markdown, and renders
- Strips the internal
<!-- ZF_NOTE_META … -->round-trip comment — you never see or edit it - Auto-saves (~2s debounce), with no "Save" button
- Updates the tab title from the note's first line automatically
- Refreshes the parent item's Source Note (debounced), so the embedded region reflects your edits
- For Read Only libraries, the tab title shows
(READ ONLY)and the editor loads but is locked
Method 2: Source Note Inline Editing
Open the parent item's Source Note (Source or Live Preview mode), scroll to the corresponding child note region, and click the 🔒 lock icon before the ZF_NOTE_BEG_… fence. The region unlocks and you can edit in place. After a ~2s debounce, ZotFlow converts the Markdown back to Zotero HTML and updates IndexedDB. The Note Editor (if open) refreshes in sync; the Source Note itself does not re-render, to avoid overwriting what you just typed.
⚠️ Editing the same note from both entry points simultaneously carries an overwrite risk. Both write to the same IDB record. If the Note Editor and Source Note are both open and both receive input within the debounce window, the last writer wins.
Deleting an Item Note
In Zotero Tree View:
- Right-click a
📝note node - Select Delete note
ZotFlow marks the note as deleted in IndexedDB, refreshes the Tree View, re-renders the parent item's Source Note (so the deleted note's editable region is removed), and shows a Note deleted. notification. The deletion is pushed to Zotero on the next bidirectional sync. If the note was never synced (syncStatus: "created"), it's removed locally immediately.
There is no undo. If you delete by mistake, recreate the note with the same content before the next sync, or restore from the Zotero side.
Sync Behavior
Item Note create/edit/delete operations are captured locally first and reconciled with Zotero on the next bidirectional sync:
| Local operation | syncStatus | Behavior on next bidirectional sync |
|---|---|---|
| Create | "created" | Push new note item to Zotero, receive the real key |
| Edit | "updated" | Push new HTML content to Zotero |
| Delete | "deleted" | Delete the note item from Zotero |
Item Notes follow the same field-level conflict resolution as regular items: if the same note is edited on both Zotero and ZotFlow between syncs, the diff viewer lets you choose which side wins.
Markdown ↔ Zotero HTML Conversion
Zotero stores notes in ProseMirror HTML format. ZotFlow converts on both read and write:
- Open/Display — IDB HTML → Markdown (
html2mdpipeline) - Save — Markdown → HTML (
md2htmlpipeline)
The conversion is round-trip safe for Zotero-supported features: rich text, headings, lists, tables, images, math formulas, code blocks, blockquotes, links, and citations.
Link Conversion (ZotFlow ↔ Zotero)
With Convert Item Note Links enabled (Settings → ZotFlow → General, default on), links inside item notes are converted at the same read/write boundary:
- Stored & synced form (IDB and Zotero) — native
zotero://links (zotero://select/…,zotero://open-pdf/…/ Zotero 7'szotero://open/…with?annotation=/?page=N), so clicking the note in Zotero navigates with Zotero's reader. Child-note links in the personal library are stored in Better Notes'zotero://note/u/<key>/format, so note-to-note links keep working for Better Notes users; inbound, those links open the note in ZotFlow (honoring the "Always Open Child Notes in Note Editor" setting). - Displayed form (Obsidian) —
obsidian://zotflow?…links, so the same click opens ZotFlow's reader (attachments, annotations, page positions included).
Conversion is round-trip stable for item, attachment, annotation, and page-level links. Anything that cannot be converted without losing its target (unknown libraries, unrecognized query parameters) is left untouched — a native link that still works beats a broken converted one. Legacy notes containing ZotFlow links are normalized to the Zotero form the next time they are edited and saved.
Independently of this setting (always on), Zotero annotation and citation spans are clickable: highlights/underlines quoted from a PDF (data-annotation) open the attachment in ZotFlow's reader at the annotation, and citation spans (data-citation) open the cited item's source note. The spans and their payloads are never modified — a display-only anchor is injected on read and always stripped on save, so the objects stay fully functional in Zotero.
An internal <!-- ZF_NOTE_META … --> comment is preserved to maintain Zotero wrapper div attributes (schema version, etc.) across round-trips. The Note Editor strips it on display and re-injects it on save — you never need to care about it.
Permission Quick Reference
| Condition | Behavior |
|---|---|
| Library mode = Bidirectional, Key has notes write | Full create/edit/delete. Changes pushed on next sync |
| Library mode = Read Only | Create and delete entries hidden in Tree; editor loads in read-only mode |
| API Key lacks notes write | Notes for items in that library are not synced and not visible in Tree View |
| Library mode = Ignored | Library not synced; notes not visible in Tree View |