Import Zotero notes

Import child notes from Zotero into the vault as standalone Markdown files, with options for batch re-import and annotation rendering.

ZotLit can import Zotero child notes as standalone Markdown files in your vault and link to them from the parent literature note.

How import is triggered

Import is link-driven. When a template or frontmatter expression references the noteLink property on a child note, ZotLit imports that note as a Markdown file. If noteLink is never referenced, no file is created for that child note.

In Liquid templates, a property access triggers import automatically:

{{ note.noteLink }}

In frontmatter expressions, mapping over noteLink triggers import for each child note:

zt.notes | map: "noteLink"

Accessing other properties (such as title) does not trigger import.

Import a single child note

When you create, update, or overwrite a literature note whose template or frontmatter references noteLink, ZotLit imports the child notes during that operation. No separate command is needed.

Metadata-only update

A metadata-only update ( ZotLit: Update literature note metadata) re-evaluates frontmatter but does not re-render the note body. If a frontmatter expression references noteLink, child notes are still imported during that update. A noteLink reference that exists only in the body template has no effect during a metadata-only update because the body is not re-rendered.

Import all child notes at once

Open the parent literature note

Open the literature note whose child notes you want to import.

Run the import command

Open the command palette and run:

ZotLit: Import child notes from Zotero

A modal titled Import child notes appears. It shows how many child notes will be imported and lists any that are already imported.

Click Import notes to proceed.

This command also appears in the right-click context menu on a literature note file.

Create-once behavior

Imported notes are created once and not automatically updated. If an imported file already exists for a child note, noteLink links to the existing file without re-importing. Editing the Zotero note afterward does not change the imported file.

To bring an imported note up to date, use the re-import commands described below.

Re-import a single note

Open an imported note

Open a note that was previously imported from Zotero (one with a zotero-note-key frontmatter field).

Run the update command

Open the command palette and run:

ZotLit: Update imported note from Zotero

A confirmation dialog appears: Update imported note: "Overwrite this file with the latest content from Zotero. Any local edits will be lost."

Click Update to proceed.

Re-import notes in batch

Batch re-import is started from the ZotLit companion, not from an Obsidian command.

Select notes in Zotero

In Zotero, select the notes you want to re-import, child notes under an item, or standalone notes. Right-click to open the context menu, then choose ZotLit > Import note(s) to Obsidian.

(This menu entry appears when the selection contains note items. If you select regular items instead, the menu shows Import child notes, which triggers a different import path.)

Confirm import in Obsidian

What happens next depends on how many notes you selected:

Single note: If the note has not been imported before, it imports directly and a toast confirms success. If it already exists in the vault, Obsidian shows a confirmation: Overwrite imported note: "Overwrite {title} with the latest content from Zotero? Any local edits will be lost." Click Overwrite to proceed, or dismiss to cancel.

Two or more notes: Obsidian opens a modal titled Import notes. It groups notes by status:

Import: new notes that do not yet exist in the vault.
Overwrite: notes whose Zotero content has changed since the last import.
Up to date: notes that have not changed in Zotero and are skipped.

The up-to-date check compares the zotero-lastmod frontmatter value in the existing file against the live dateModified timestamp in Zotero, rounded to whole seconds.

Click Import notes to proceed.

Large selections

A selection too large to fit in a protocol link falls back to an HTTP connection to Obsidian. If the ZotLit server is not enabled in Obsidian, Zotero shows a notice asking you to enable it or select fewer items. See Set up live updates for the server setting.

Import folder

Imported notes are saved to the folder configured in Settings > Note import > Imported note folder (default: zotero_notes). The folder is created automatically if it does not exist. Each filename includes a short random suffix to guarantee uniqueness.

Citations in imported notes

The imported note's body is the Zotero note's HTML converted to Markdown. Citations within it render through your cite template.

Each cited reference resolves its citekey in this order:

The live Zotero item's own citation key.
The citation snapshot embedded in the Zotero note.
A visible sentinel: the Zotero item key with ? appended (e.g. -@ABC123? in the default cite template). The trailing ? makes unresolved citations greppable in your vault.

If every cited reference within a single citation is unresolvable (no citekey from any source), ZotLit keeps that citation's original HTML verbatim. Nothing is lost.

Render annotations from template

By default, annotation paragraphs in imported notes keep the HTML that Zotero inserted: highlighted or underlined excerpts with a citation link.

Turn on Settings > Note import > Render annotations from template to render those paragraphs through your annotation template instead, producing the same rich callouts used in literature notes.

Replace on refresh

With this setting on, each annotation's text, comment, color, page, and image are taken fresh from Zotero. Edits you made to that paragraph inside the imported note are replaced. This is why the setting is off by default.

What is rendered

Only paragraphs that still match the original Zotero structure are rendered from the template. A paragraph is left untouched when:

You typed text before the excerpt.
You added other elements to the paragraph (a second annotation, extra formatting).
The paragraph is nested inside a list item, blockquote, or table cell.
The annotation was deleted in Zotero and can no longer be fetched.

Highlight, underline, and image annotations are eligible for template rendering. Note and text annotations (which carry no excerpt) are kept as Zotero inserted them.

Text after the citation

Text you add after the citation mark (the comment slot) is not protected. Zotero places the annotation's own comment in that position, so on refresh it is replaced along with the rest of the paragraph. Place notes you want to keep in a separate paragraph.