Import Zotero notes
Import Zotero child and standalone notes into the vault as Markdown files, with batch re-import and annotation rendering.
ZotLit can import Zotero child notes as standalone Markdown files in your vault. A literature note whose template uses noteLink links to them.
How import is triggered
Import is explicit. A child note becomes a Markdown file only when you run an import command, or start an import from Zotero. Creating, updating, or overwriting a literature note never imports its child notes.
A template can still link to child notes through the noteLink property:
{{ note.noteLink }}When an imported file exists for the child note, noteLink links to that file. Otherwise it renders a zotero:// link that opens the note in Zotero. The Template Workbench preview shows the same link.
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 ZoteroA modal titled Import child notes appears. It shows how many child notes will be imported and lists any that are already imported.
Select 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. 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.
If an attachment was skipped because its folder was not approved, a notice lists the blocked source folder. This can happen with a Zotero linked file, which Zotero stores in an external folder instead of its data directory. See Zotero's guide to linked files.
Select Open ZotLit settings, open Settings > ZotLit > Attachments > Approved folders, and approve the folder if you trust it. Then re-import the note to copy the attachment. Approval applies to future imports and does not update earlier imports automatically.
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 ZoteroA confirmation dialog appears: Update imported note with the body Overwrite this file with the latest content from Zotero. Any local edits will be lost.
Select Update to proceed.
Import every note in a library or collection
This path imports both kinds of note in one action: the child notes attached to your regular items and the standalone notes filed alongside them.
For the whole library, open the command palette and run:
ZotLit: Import all child and standalone notesFor one collection, right-click it in the Zotero sidebar and choose ZotLit > Import Child and Standalone Notes. Nested subcollections are included. The same entry on My Library or a group library covers that whole library.
Obsidian opens the Import notes modal described below, listing every note it found. Review the list, then confirm to start the batch.
A note with no parent literature note is listed under Import without a parent literature note (…) rather than under Import (…). That group states the profile its notes import through and lets you pick another one: the choice governs the new notes in the group.
The Obsidian command covers every library in your library scope (set in Settings > ZotLit). The Zotero entries cover the library or collection you right-clicked, whatever your library scope is.
If the collection no longer exists in your Zotero database, Obsidian reports Collection not found in Zotero.. If the library no longer exists, it reports That Zotero library is not available..
While more than one library contributes notes, the Import notes modal names the library beside each heading. If a selected library is missing from your Zotero database, the import continues over the rest and states how many libraries it skipped. If none of your selected libraries is available, no modal opens and a notice reports No library in the library scope is available..
Re-import notes in batch
ZotLit Companion, the Zotero add-on, starts batch re-import from Zotero.
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 Selected Notes.
(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 with the body Overwrite … with the latest content from Zotero? Any local edits will be lost. Select 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.
- Import without a parent literature note (…): new notes with no parent literature note. The group names the profile they import through, and you can change it. See Import every note in a library or collection.
- 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, in whole seconds.
Select 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.
Security prompt in Zotero
Zotero may show a confirmation dialog each time it opens an obsidian://
link. See Suppress the Zotero security
prompt to disable it.
Profile of an imported note
An imported note records the profile that imported it in its zotlit-profile frontmatter field. ZotLit writes the field only when that profile is not the Default profile, so a note without it was imported under Default.
A re-import reads the field back, so the note keeps rendering through the profile that created it. When that profile no longer exists, ZotLit reports Use Switch profile… to replace the unavailable profile “…” on imported note “…”. and offers Switch profile….
Import folder
Imported notes use their profile's Imported note folder (default: zotero_notes). The Default profile's binding sits at Settings > ZotLit, and another profile sets importFolder in its own document. 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 the citation text, always as the main variant.
Each cited reference resolves its citation key 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 built-in citation text). The trailing?makes unresolved citations greppable in your vault.
If every cited reference within a single citation is unresolvable (no citation key from any source), ZotLit keeps that citation's original HTML verbatim. Nothing is lost.
Use colored highlight syntax
- Turn on Settings > ZotLit > Imported notes > Use colored highlight syntax. A profile other than Default sets it in its own profile document.
- Open Highlight mappings to set the output for each Zotero color. These mappings apply to all profiles.
- Choose HTML mark, a circle emoji (🔴 🟠 🟡 🟢 🔵 🟣), or Custom.
- For Custom, enter one emoji in the field below. Combined emoji such as 👩🔬 are supported.
- Import or re-import the note to apply your mappings.
By default, red, orange, yellow, green, blue, and purple use matching circle emoji. Magenta, gray, and plum use colored HTML marks. You can change any of these nine mappings.
An emoji mapping adds the selected emoji at the start of Colored Highlight Syntax:
==🔵Highlighted text==Your theme or another plugin must support the selected emoji to render its highlight color. Choosing a custom emoji does not add that rendering support.
The setting applies to highlights created in Zotero's note editor and inline annotation excerpts. Annotation excerpts keep their Zotero backlinks:
[==🔵Highlighted text==](zotero://...)Highlights with unrecognized or missing source colors remain HTML. Empty or invalid custom emoji also use HTML marks. ZotLit keeps HTML when the text contains == because it conflicts with the Markdown delimiter.
The setting is off by default. Turning it off uses HTML marks and keeps your saved mappings.
Changes affect later imports and re-imports; existing files stay unchanged until re-imported. When Render annotations from template is on, annotation-template output stays unchanged.
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 > ZotLit > Imported notes > Render annotations from template for the Default profile, or set importAnnotationsAsTemplate in a profile document. ZotLit renders those paragraphs through the Annotation Section of that profile, producing the same rich callouts used in literature notes.
Replace on refresh
With this setting on, each annotation's text, comment, color, and page come from its saved Zotero data. Image and ink excerpts are prepared during import. 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, image, and ink annotations are eligible for template rendering. Note and text annotations (which carry no excerpt) are kept as Zotero inserted them.
Image and ink paragraphs use live excerpt images with both PDF readers closed. Ordinary embedded images keep the snapshots stored in the Child Note. A paragraph converted through the annotation template does not also copy its stored snapshot.
Re-import selects a new image version only for that Imported Note. Other notes and older image files stay unchanged. A failed refresh keeps a verified previous image when available; otherwise it writes an explanation and source link. Other content and notes can still import if an image fails.
With Import attachments off, live excerpts create no new image files. The import summary counts only images requested by the template and combines the results for a batch.
The existing re-import rules still apply. Batch import skips notes whose Zotero modification time has not changed, even if a live annotation changed. Use the single-note re-import command to refresh such a note. With a missing annotation or blank annotation template, ZotLit converts the stored paragraph as ordinary note content.
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.
See also
Last updated on