Literature notes and the managed region
How ZotLit identifies literature notes and uses a managed region to separate generated content from your own writing.
A literature note is an Obsidian Markdown file linked one-to-one with a Zotero item. A profile can mark a region inside the note that ZotLit keeps up to date, without overwriting anything you write yourself.
What makes a file a literature note
ZotLit identifies a literature note by a single frontmatter field: zotero-key. Any Markdown file in your vault that contains this field is treated as a literature note, regardless of filename or folder location.
---
zotero-key: ABC123XY
---The update and overwrite commands only appear in the command palette and context menu when the active file has a resolvable zotero-key.
The managed region
Every literature note is governed by one profile. The profile supplies the note source, the text ZotLit renders into the note, and the note source can mark part of it with a managed block, {% managed %} and {% endmanaged %}. The Default profile has no managed block: its body renders once, when ZotLit creates the note, and is yours afterwards. See Profile document for the document that carries the source, and How templates work for how ZotLit finds it.
When ZotLit creates or overwrites a literature note, it renders the note source. Where the note source has a managed block, its output goes into the note body inside comment markers:
%%zt-managed%%
...generated content...
%%/zt-managed%%ZotLit owns everything between these two markers. Your own writing goes above or below the managed region.
What the region contains
The managed region holds the output of the managed block in the profile that governs the note. The Default profile has no managed block, so a new default note has no managed region. Its Annotations section holds a live query block that shows your annotations as interactive cards, and stays current without an update. A note made with an earlier default can still carry the markers; there the region holds that section.
If you customize your profile to render annotations as text rather than a query block, each annotation renders through the profile's Annotation Section. See Default templates.
Text outside a managed block renders once, at creation time. In the Default profile, that covers the title heading, the Zotero backlink, and the attachment file links. The attachment links point to the original files and do not copy them into the vault. For a Zotero linked file, the original can be in an external folder. See Zotero's guide to linked files. A link to a PDF in your Zotero library opens in Obsidian when you click it, unless Open PDF file links in Obsidian is off. Updates do not touch these lines.
How updates use the region
ZotLit: Update literature note refreshes the frontmatter with the current Zotero metadata and re-renders the managed block of the profile that governs the note, replacing the managed region with the new output. Everything outside the markers stays exactly as you left it. This is how ZotLit can pull in new annotations or updated metadata without disturbing your own notes, links, or tags.
A profile whose note source has no managed block updates the frontmatter only. The note body has no region to replace. The built-in Default profile is the one exception: on a note made with an earlier default that still has the markers, an update re-renders the region with the Annotations section.
To stop ZotLit managing a region, delete the %%zt-managed%% and
%%/zt-managed%% lines. The next update leaves the body untouched.
ZotLit: Update literature note metadata is a lighter operation. It refreshes frontmatter only and never touches the note body.
Notes without a managed region
Notes created with ZotLit v1
Literature notes created with ZotLit v1 have a zotero-key and are recognized as literature notes, but they contain no managed region markers. Running ZotLit: Update literature note on a v1 note refreshes its frontmatter and leaves the body untouched. ZotLit reports Properties updated. This note has no managed region, so its body stayed unchanged..
To recover the full update workflow on a v1 note, see Keep notes up to date.
Overwrite versus update
ZotLit: Overwrite literature note is a separate, destructive command. It regenerates the entire note body from the note source of the profile that governs the note, discarding everything below the frontmatter block. Frontmatter keys managed by ZotLit are refreshed; other frontmatter keys you added are kept. A confirmation dialog gates the action.
Keep notes up to date covers both actions, and the batch update that ZotLit Companion starts from Zotero.
See also
How templates work
The three kinds of template document and the two template languages.
Profiles
How a profile decides the name, folder, properties, and body of a note.
Keep notes up to date
Step-by-step procedures for single and batch note updates.
Create and open literature notes
Open or create a note from the quick switcher or a citation key.
How ZotLit connects to Zotero
The database connection, protocol links, and live updates.
Last updated on