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: 从 Zotero 导入子笔记A modal titled 导入子笔记 appears. It shows how many child notes will be imported and lists any that are already imported.
Select 导入笔记 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 打开 ZotLit 设置, open Settings > ZotLit > 附件 > 已批准文件夹, 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
Re-importing replaces the file with the latest content from Zotero, so any local edits are lost.
Open an imported note
Open a note that was previously imported from Zotero (one with a zotero-note-key frontmatter field).
Run the overwrite command
Open the command palette and run:
ZotLit: 覆盖导入的笔记A confirmation dialog appears: 覆盖导入的笔记 with the body 使用 Zotero 的最新内容覆盖此文件。任何本地编辑都将丢失。
Select 覆盖 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: 导入所有子笔记和独立笔记For one collection, right-click it in the Zotero sidebar and choose ZotLit > 导入子笔记与独立笔记. Nested subcollections are included. The same entry on My Library or a group library covers that whole library.
Obsidian opens the 导入笔记 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 无父文献笔记的导入（…） rather than under 导入（…）. 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 在 Zotero 中未找到收藏集。. If the library no longer exists, it reports 该 Zotero 文库不可用。.
While more than one library contributes notes, the 导入笔记 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 文库范围中没有可用的文库。.
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 > 导入所选笔记.
(This menu entry appears when the selection contains note items. If you select regular items instead, the menu shows 导入子笔记, 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: 覆盖导入的笔记 with the body 用 Zotero 的最新内容覆盖 …？任何本地编辑都将丢失。 Select 覆盖 to proceed, or dismiss to cancel.
Two or more notes: Obsidian opens a modal titled 导入笔记. It groups notes by status:
- 导入（…）: new notes that do not yet exist in the vault.
- 无父文献笔记的导入（…）: 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.
- 覆盖（…）: notes whose Zotero content has changed since the last import.
- 最新 (…): 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 导入笔记 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 请使用“切换配置方案…”为导入笔记“…”更换不可用的配置方案“…”。 and offers 切换配置方案….
Import folder
Imported notes use their profile's 导入的笔记文件夹 (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 > 导入笔记 > 使用彩色高亮语法. A profile other than Default sets it in its own profile document.
- Open 高亮映射 to set the output for each Zotero color. These mappings apply to all profiles.
- Choose HTML 标记, a circle emoji (🔴 🟠 🟡 🟢 🔵 🟣), or 自定义.
- For 自定义, 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 使用模板渲染标注 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 > 导入笔记 > 使用模板渲染标注 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 导入附件 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