Changelog

This release rebuilds the Template Workbench as one view. ZotLit Companion 2.2.2 ships with it and has no changes of its own, so Companion 2.2.0 and 2.2.1 keep working.

HighlightsCopy anchor link

The Template Workbench in one viewCopy anchor link

The template editor, the Fields panel, and the Note preview now sit together in one view, in its own Obsidian window. Choose a paper once and all three show it.

• Note preview: beside the editor in a wide window, under it in a narrow one. A button in its header switches between reading view and Markdown.
• Fields panel: select 字段 to find a field, see its value, and insert it. Pin it to keep it beside the editor.
• Dividers: drag them to resize the parts, as in Obsidian.

See Template Workbench View.

Breaking ChangesCopy anchor link

One command opens the Template WorkbenchCopy anchor link

ZotLit: 打开模板工作台 is now the only way in. It works from a profile, a template document, or a literature note. These commands and menu entries are gone:

• "Switch to template workbench view". Use ZotLit: 打开模板工作台.
• "Customize this note's template". Run ZotLit: 打开模板工作台 from the note. It opens the note's profile with the note's paper selected. 更新此笔记 still applies your change to that note.
• "Open note preview". The Note preview is now part of the view.

If you set a hotkey for one of these, set it again on ZotLit: 打开模板工作台. ZotLit 2.2.1 also had a second command with that name, for profile documents. A hotkey on it is gone too.

A workspace that kept a Note preview tab from 2.2.1 shows it as an empty tab. Close it.

What's NewCopy anchor link

Other improvementsCopy anchor link

• You can now put an annotation into a note straight from the PDF. Click the annotation mark to select it, then drag the mark into the note. ZotLit inserts it as a drag from the annotation view does. See Drag an annotation into a note.
• To change the order of properties, drag a row on the Properties tab by its handle (拖动以调整顺序). The handle shows when you point to the row. You can also select the handle and press Alt+Arrow Up or Alt+Arrow Down. The handle replaces the Move up and Move down buttons. See Configure frontmatter properties.
• The view's pane menu is shorter. Each action in the view header also has an entry there.
• Note embeds in the Note preview now show a placeholder with the note's name and whether the note exists. Before, the preview loaded the embedded note or offered to create a missing one.
• Query blocks and query file embeds in the Note preview now list each view with its layout and rows. They mark the views that show 仅限本笔记的条目, and they show problems in the query text.
• Each Template Workbench tab now links to the docs page for that part of the template, such as 属性指南 on the Properties tab. The 帮助 menu has the 模板指南, 模板语法, and 模板数据参考. The template data explorer links to the 模板数据指南.
• The dividers in the Library View now look like Obsidian's pane dividers.

Bug FixesCopy anchor link

• In the Template Workbench, after you moved a Properties row, every row showed its raw rule for a moment. The Name tab example blinked the same way. Now each row keeps its value while the preview renders again.
• ZotLit: 导出带引文的笔记 could read a --- line in the note body as Properties. Now the line stays in the exported document.
• If you run Pandoc yourself, a --- line had the same problem. A line that starts with % after the Properties became the document title. Now both stay as text. Save the ZotLit integration pair again to get the fix.
• In a PDF opened in its own window, the popup of a selected annotation moved to the main window when you clicked there. Now it stays with the PDF.
• In a separate window, some parts of ZotLit did not adapt when you resized the window: a pinned popover, the Library View layout, and the abstract on a reading card. Now they adapt as in the main window.
• In a separate window, some actions were slow while the main window was hidden: the Cited by search, the save of a query file, the refresh of a Query View, and the item picker. Now they run at full speed.
• ZotLit now finds your Zotero profile in more setups. On Linux, it also finds a Zotero profile under ~/.config/zotero. On Windows, it follows an AppData folder that was moved to another place.

This is a maintenance release after 2.2.0. ZotLit Companion 2.2.1 ships with it and has no changes of its own, so Companion 2.2.0 keeps working.

What's NewCopy anchor link

Update notesCopy anchor link

• The new ZotLit: 更新笔记 command opens a dialog. 更新全部笔记 updates every existing note. 更新当前笔记 shows when a literature note is open.
• The dialog creates no notes unless you ask. The checkbox 更新全部笔记时，也为没有笔记的条目创建笔记 is off by default.
• After you save a template in the web Template Workbench, the notice action now reads 更新现有笔记. It changes only the notes you already have. It used to read "Update all notes".
• When you update a whole library or collection, ZotLit now shows the confirmation even if it holds one item.
• The older update commands stay available for keyboard shortcuts.
• "Update imported note from Zotero" is now ZotLit: 覆盖导入的笔记, so the name says what it does. Your hotkeys keep working.

See Start with Update notes and Apply a template change to some notes.

Every field in the FilterCopy anchor link

The Query View Filter used to list 8 fields, so a journal or DOI condition needed an expression. It now lists every Zotero field, with the common ones first. Whole date fields sit beside their parts.

• Everyday words find a field, in English or Chinese. For example, journal or 期刊 finds the Publication field.
• These words also work in the Properties, Sort, and Group lists and in the completion list of filter expressions.
• A saved expression on such a field now opens as a visual row.
• Profile Match shares the same list.

See Filter the rows and Profile Match.

Other improvementsCopy anchor link

• Text filter rows now ignore letter case: 包含 and 不包含. To keep case, use the new rows 包含，区分大小写 and 不包含，区分大小写. Saved filters keep their results and open as match case rows. This applies to the Query View Filter and Profile Match.
• The filter expression field is easier to use in Query View filters, Formulas, and Profile Match:
  • (, [, and quotes now close themselves. Typing one wraps selected text.
  • An empty field shows the hint 输入筛选表达式.
  • 可视化编辑 turns a blank expression into an empty condition row.
  • When an expression has no visual form, the button's tooltip says 此表达式只能以文本编辑.
• The Query View is faster in large libraries. On a 100,000-item test library, the first page, sorting, and common title searches came back about 3 to 4 times faster. Filters on Tags or Collections are faster too. Very broad searches take as long as before.
• The Workbench's 标注 tab now says that edits apply to each annotation you insert from now on. Its help names the 标注示例 pane.

Bug FixesCopy anchor link

• In a large library, item search could pause after you edited items in Zotero. This is the search in the Library View, the quick switcher, the citation suggester, and the Template Workbench. Now it stays responsive, also while you update the notes of a whole library.
• When you converted 2.1 templates, a frontmatter field that failed the conversion check stopped the conversion. The Profile editor stayed locked, so the only repair was editing the settings file. Now the conversion finishes, keeps the field as you wrote it, and a notice names it. ZotLit refuses to create notes until you fix the field, and the refusal names it. See Properties that need a fix.
• Other conversion failures did nothing visible when you selected 转换模板. Now a notice says what went wrong. For a problem in a template file, it also offers moving the file out of the template folder to use the built-in templates.
• A Template Workbench preview with citations and no Pandoc engine showed as broken, with the heading Citation style "undefined". Now the preview stays valid and shows a hint. 打开设置 takes you to the Pandoc 引擎 setting.
• Some disks ignore letter case, the usual setup on macOS and Windows. There, a template folder set to templates beside a vault folder Templates broke template customizing. It failed with "Could not create the template document". Now ZotLit finds the existing folder. Notes also move into such folders correctly.
• Tooltips on controls inside popups, such as the Query View Filter and Properties popups, appeared behind the popup. Now they show above it.
• The function argument hint in filter expressions flashed and jumped as the cursor moved. Now it stays in place.

This is the first stable release of ZotLit 2.2. It collects every change since 2.1. For a guided tour of the main features, read the release post.

Breaking ChangesCopy anchor link

Obsidian 1.14.5 or laterCopy anchor link

ZotLit 2.2 needs Obsidian 1.14.5 or later. ZotLit 2.1 needed 1.13.4. On an older Obsidian, the plugin stays at 2.1.4 and does not update. Update Obsidian first, then update ZotLit. See Install ZotLit.

Update ZotLit Companion together with the pluginCopy anchor link

ZotLit 2.2 does not accept requests from ZotLit Companion 2.1. Until you install Companion 2.2.0 in Zotero, these stop working and ZotLit asks you to update the Companion:

• Live updates of literature notes when you change an item in Zotero.
• The Obsidian note column in Zotero's item list.
• Updating or importing many selected items at once from Zotero.

Links that open a single item from Zotero still work. See Install ZotLit Companion.

PDF file links open in ObsidianCopy anchor link

A click on a PDF file link in a note now opens the PDF in Obsidian's reader, not in your system's PDF app or in Zotero. This includes the file:/// attachment links that the 2.1 default template wrote into your notes. To keep the old behavior, turn off 在 Obsidian 中打开 PDF 文件链接 and 在 ZotLit 阅读器中打开标注链接 under Settings > ZotLit > 阅读器.

Eta tag suggestions removedCopy anchor link

Obsidian's note editor no longer suggests Eta tags in template files, and the Auto-pair Eta tags setting is gone. Edit templates in the Template Workbench, which completes and pairs tags.

2.1 template files become profile documentsCopy anchor link

2.1 template files keep working until you convert them. The Welcome view and the settings offer the conversion. It folds the note, managed-region, filename, and annotation files into zotlit-profile.default.md, the two citation files into zotlit-citation.md, and other files into partials. ZotLit checks that the output stays the same before it writes, then moves the old files to the trash.

Until you convert, the frontmatter field list has no editor, and you cannot add or import a profile of your own. See Converting 2.1 template files.

New default literature notesCopy anchor link

A new note from the default template is written once. Its body has the title, the Zotero link, attachment links, and an Annotations section with a query block that reads Zotero live. After that, the body is yours to edit.

• ZotLit: 更新文献笔记 refreshes the note's properties and leaves the body as you wrote it.
• The default template adds no %%zt-managed%% markers and no list of Zotero child notes.
• Notes you already have keep their markers, and an update still refreshes the text between them. If you use the default templates, that text is now the Annotations query block: the next update replaces the static annotation list and the list of child notes with it. Annotations in the block show only inside Obsidian, not in search, Publish, or other apps. To keep the static text, delete the two marker lines before you update.
• If you customized or duplicated the Default profile, add a {% managed %} block to its document to keep refreshing older notes.

See Keep notes up to date and Literature notes and the managed region.

Child notes import only when you askCopy anchor link

Creating or updating a literature note no longer writes Zotero child notes into your vault. Run ZotLit: 从 Zotero 导入子笔记 or ZotLit: 导入所有子笔记和独立笔记, or start an import from Zotero. In a template, noteLink links to the imported file when one exists, and opens the note in Zotero otherwise. See Import Zotero notes.

Export stops on an unknown key or a missing styleCopy anchor link

• ZotLit: 导出带引文的笔记 now reads literal @citation-key text, as Pandoc does. A key that matches no item, or several items, stops the export and names the keys. Before, such a note exported without a reference list.
• Exports format citations in the style the note uses in Obsidian. When Zotero cannot supply that style, the export stops and tells you. Before, it fell back to a bundled style.
• If you run Pandoc yourself with ZotLit's integration files, save them again from this version.

See Export a note with citations and Export with native Pandoc.

Settings movedCopy anchor link

• Maintenance is now Settings > ZotLit > 高级, which also holds the template folder, the template engine rows, and the local server.
• The Database and Library pages merged into Settings > ZotLit > Zotero. Connection and database overrides are on its Zotero 位置 sub-page.
• Note import is now Settings > ZotLit > 导入笔记, and the citation text is under Settings > ZotLit > 引文.

Row names are unchanged, so Obsidian's settings search still finds them. See Where settings moved.

Agent template commands retiredCopy anchor link

Eight template and frontmatter commands from ZotLit 2.1 are retired from the Obsidian CLI. Use zotlit:template-inspect, zotlit:template-data, and zotlit:template-check instead. See the Template Workbench CLI reference.

HighlightsCopy anchor link

Library ViewCopy anchor link

Browse your Zotero library in an Obsidian tab. Run ZotLit: 打开 Zotero 文库 or select the ribbon icon. The view reads your local Zotero database, so it works without the Companion.

• The tree shows your libraries, collections, and paper counts. You can collapse and resize it.
• Quick filters show 未读, 有批注, papers with literature notes, or papers with PDFs. You can also filter by tag.
• Drag a paper into a note to cite it.
• The Reading Card shows the metadata, the abstract, the attachments, and annotation counts by color. Show or hide it with 显示条目详情 or Space. With no paper selected, it shows counts for the library or collection.

See Browse your library in the Library View.

Read and annotate PDFs in ObsidianCopy anchor link

A paper's PDF opens in an Obsidian tab beside your note. The file stays in Zotero's storage, outside your vault. Your Zotero highlights and notes show on the page in their Zotero colors.

• Open a PDF with ZotLit: 打开 PDF, with Shift+Enter in ZotLit: 打开文献笔记快速切换器, from a file link in a note, or from Zotero's item menu and reader page menu.
• The toolbar creates the same annotations as Zotero's reader: highlight, underline, note, text, image, and ink.
• Change an annotation's color, comment, or tags, drag it to move or resize it, and undo with Ctrl+Z or Command+Z.
• With Zotero 10, every change saves to Zotero and syncs like an annotation you made there. If both apps change one annotation, ZotLit shows both versions and you choose one.

Editing needs Zotero running on the same computer, Zotero's Allow other applications on this computer to communicate with Zotero setting turned on, and your permission once. Select 允许编辑 in the annotation view and choose Always Allow in Zotero. Only PDFs open in Obsidian; EPUBs and web snapshots stay in Zotero. See Open an item's PDF in Obsidian and Edit PDF annotations in Obsidian.

ZotLit Query and the Query ViewCopy anchor link

Show your papers in a table, much like Obsidian Bases. Create a .zotquery query file with ZotLit: 新建查询文件, or embed a query block in any note.

• Show results as a Table, Cards, a List, or Annotations.
• Add a literature note property such as reading-status as a column, then edit cells in place. Values save to the note, so Properties and Bases show the same values.
• A paper without a note shows 无笔记. Type a value there to create the note.
• Filter with nested condition groups or with an expression. The expression editor colors the text, underlines errors, and completes field and function names.
• Sort, group, search, add Formula columns, rename columns, and export to CSV or TSV.

See Track reading status in the Query View, Query files and query blocks, and Use query files.

What's NewCopy anchor link

Citations in the graph viewCopy anchor link

• Obsidian's graph draws an edge from a note to every work it cites. A cited work without a literature note shows as a dimmed Cited Work Node.
• Rows in the graph's Filters and Display sections choose citation types, author and title labels, colored citation edges, and a hover popover.
• Select a Cited Work Node to create its literature note. Right-click it to open it in Zotero or copy its citation key.
• ZotLit: 打开引用关系图谱 and ZotLit: 打开局部引用关系图谱 open a graph arranged as a research map.

This is on by default. Turn it off with 在关系图谱中显示引用 under Settings > ZotLit > 引文. See Explore citations in the graph view.

Literature note profilesCopy anchor link

• Each profile is one Markdown document that holds the note name, the folder, the properties, the body, and the annotation format.
• zotlit-citation.md holds the citation text for the whole vault, and partials hold text that several profiles share.
• Manage profiles under Settings > ZotLit > 文献笔记配置方案. A new profile needs only a name; leave the folder empty to use the Default profile's folder.
• A Profile Match picks a profile by library, item type, tag, or collection.
• ZotLit: 切换文献笔记配置方案 moves a note to another profile and keeps its subfolders.
• Links and menu commands from Zotero can name a profile.

See Profiles, Profile Match, and Use a different template for different notes.

Template WorkbenchCopy anchor link

• Edit a profile in a desktop view with the fields on one side and a live note preview on the other. ZotLit: 打开模板工作台 opens all three panes.
• From a literature note, ZotLit: Customize this note's template opens its profile with that paper selected, and 更新此笔记 applies your change to it.
• Tabs cover the note, properties, annotations, name and folder, and match. The name and folder tab shows the full vault path the note gets.
• The editor highlights Liquid and Eta, suggests fields and partials, and lists problems with their place in the document.
• Turn selected text into a partial with 提取为片段….
• The template data explorer groups fields into sections and copies a field as a value, a path, or a loop.

See Template Workbench View, Customize a template, and Explore template data.

Annotation viewCopy anchor link

• The view has compact cards with the quote, your comment, the tags, and the page. Image and ink annotations show their picture.
• Select several cards, then recolor them with the keys 1 to 8, copy their text, or delete them. One undo reverses the group.
• Color and tag filters open as popovers. Save the view and its filters as a .zotquery file with 另存为查询文件….
• The view follows the active tab or the Zotero reader, or stays pinned to one paper.
• 插入到笔记 in a card's menu inserts the annotation at your cursor. Inserted annotations get correct spacing around the text.
• The page chip opens the PDF in Obsidian when the file is on this computer, and in Zotero otherwise.
• After the update, a pinned paper can open on its first attachment, and a saved filter can open empty. Pick the attachment or filter once, and the view remembers it.

See Use the annotation view.

Annotation links and citationsCopy anchor link

• Annotation links in notes are Zotero open links that name the annotation, so they work on every computer where you open the vault. A link opens the PDF in Obsidian when the file is there, and Zotero otherwise. See Zotero open links.
• Hover an annotation link to see the quote, your comment, the page, and the color, or the image. Below the annotation, the popover shows the paper's reference with the same buttons as the citation popover. An annotation on a standalone PDF shows alone.
• The default annotation layout puts the paper's citation after the quote and uses the page label as the link.
• Turn on 批注引用 under Settings > ZotLit > 引文 to list the paper in the 参考文献 and 被引用 sidebars.

Turn on 将批注链接显示为引用, also under Settings > ZotLit > 引文 and off by default, to show an annotation link with no link text, such as [](zotero://…), as a citation of its paper. The annotation's page becomes the locator, as in [@key, p. 12], and the citation shares the note's numbering. Selecting the citation still opens the annotation. The option needs 批注引用 and 显示格式化引用. See In-text citations.

Show in LibraryCopy anchor link

在 Zotero 文库中显示 takes you to a paper in the Library View. Find it in the citation popover, the 参考文献 and 被引用 sidebars, the graph menu, a literature note's file menu, and as Alt+Enter in the quick switcher. The ZotLit: 在 Zotero 文库中显示条目 command does the same, and templates get a zt.librarylink variable. See Show a paper in the library.

Recent papersCopy anchor link

Recent lists put the papers you worked on last at the top. Opening a note, reading a PDF, citing, and editing all count. The Library View, the quick switcher, the citation suggester, and the Template Workbench share this order. With Zotero editing on, reading a PDF in Obsidian updates Zotero's Recently Read list. See How Recent orders papers.

Citations and the suggesterCopy anchor link

• With nothing typed, the citation suggester and ZotLit: 插入 Markdown 引用 list the papers the note already cites first.
• Suggester results read as one line with the venue, volume, and pages, and mark group library items.
• Hovering from one citation to the next moves one popover.
• A citation with a locator writes Pandoc's braced form, [@key, {p. 62}].
• Templates gain a LaTeX citation filter: tex_cite in Liquid and texCite in Eta. See tex_cite.

See Insert citations.

Search and performanceCopy anchor link

• Database reads, search, and citation lookups run in the background, so Obsidian stays responsive in large libraries.
• 中文分词器 under Settings > ZotLit > Zotero is an optional download. It splits Chinese titles into words, so a search finds a word in the middle of a title.
• ZotLit: 创建或更新所有文献笔记 shows its confirmation in about one second for 10,000 new notes, down from about ten.
• Batch confirmations group rows by profile and load each group when you expand it. See Keep notes up to date.
• Notes with many citations open and update faster.

ZotLit Query CLICopy anchor link

Query your Zotero library from the Obsidian CLI with zotlit:query. Search, filter, group, and pick fields from items, attachments, and annotations, and export JSON for scripts or AI agents. zotlit:query-values, zotlit:query-schema, zotlit:query-guide, and zotlit:query-cancel help you build and run queries. See How ZotLit Query works and Query your Zotero library.

Imported notesCopy anchor link

Settings > ZotLit > 导入笔记 > 高亮映射

maps each Zotero highlight color to an emoji, a mark, or a custom emoji. See Import Zotero notes.

ZotLit CompanionCopy anchor link

• 笔记打开位置 in Zotero's ZotLit settings chooses where notes opened from Zotero appear: the active tab, a new tab, a split, or a new window.
• Zotero's item menu and reader page menu open a PDF in Obsidian.
• ZotLit links take a paneType parameter with the same choice. See Where the link opens.

Other improvementsCopy anchor link

• File and tab menus put ZotLit entries in their own groups beside Obsidian's.
• Item pickers open with their rows ready or show a loading message.
• The ZotLit: 打开文献笔记快速切换器 search box says what you can search by.
• The export dialog shows the destination as a short, readable path.
• The Welcome view has an optional step to install the ZotLit Companion. See Install ZotLit Companion.
• Migrate from Zotero Integration maps that plugin's templates onto profiles.

Bug FixesCopy anchor link

• Pressing Enter or clicking right after typing in a picker could act on an earlier search and insert the wrong citation or create the wrong note. Now Enter waits for the results of what you typed.
• A search for an eight-letter word, such as "thinking", found nothing. Now it finds the matches.
• With 将引用作为链接打开 off, a click on a citation did not put the cursor in it. Now the cursor goes where you clicked.
• [[@key]] was read as a citation. Now it is an ordinary wikilink.
• An inserted citation such as [@key] got a space after it. Now punctuation can follow it directly.
• Editing the locator in [@key, p. 5] opened the citation suggester. Now it stays closed.
• A citation inside the prefix or suffix of another citation broke its Pandoc export. Now the inner citation exports as text and its work stays in the bibliography.
• Word exports showed a callout as raw [!type] text, turned a quote under a line of text into plain text, and gave the reference list no heading. Now a callout becomes a quote with a bold title, the quote stays a quote, and the reference list has a heading in the citation style's language.
• Live note updates moved your reading position. Now the note stays where you were.
• ZotLit: 更新文献笔记 was not available with the cursor in the note title or Properties. Now it works from anywhere in the note.
• A dragged annotation dropped at the end of a sentence joined that line. Now it goes in as its own block.
• Inserting an annotation into a note in Reading view wrote into the hidden editor. Now ZotLit asks you to switch to an editing view.
• In Live Preview, the closing %%/zt-managed%% marker hid inside the last callout. Now it stays outside.
• The 被引用 view showed zero counts when no literature note was open. Now it shows counts only for a literature note.
• In Zotero, right-clicking a PDF attachment opened an empty ZotLit submenu. Now the submenu is dimmed.
• When another service used Zotero's port, the connection check failed with an unclear error. Now it asks you to open Zotero and check its settings.
• Welcome view steps stayed to-do after you completed them. Now they show as done.
• ZotLit: 打开欢迎视图 replaced the active note. Now it opens in a new tab.
• Turning ZotLit off and on quickly could lose commands or show a start-up error. Now ZotLit starts cleanly.

ZotLit copies text from Zotero to Obsidian only when you ask. There is no automatic sync in either direction.

Breaking ChangesCopy anchor link

The default literature note body is yours after creationCopy anchor link

A new literature note made with the default template is written once, as a copy of what Zotero holds when you create it. The body has the title, the Zotero link, attachment links, and the Annotations section with its query block. After that, the body is yours to edit. Your edits to it never go back to Zotero, and a later change in Zotero reaches it only if you overwrite the note.

ZotLit: 更新文献笔记 now refreshes the note's properties and leaves the body as you wrote it. The annotations query block reads Zotero live, so new highlights appear without an update. It is a view of Zotero rather than a copy. See Keep notes up to date.

The default template no longer adds %%zt-managed%% markers. It also no longer lists the paper's Zotero child notes under a "Notes" heading. ZotLit: 覆盖文献笔记 still replaces the whole body after you confirm.

Child notes import only when you askCopy anchor link

Creating, updating, or overwriting a literature note no longer imports Zotero child notes into your vault. Before, a template that used noteLink created a Markdown file for each child note along the way.

A child note now becomes a file only when you import it. Run ZotLit: 从 Zotero 导入子笔记 or ZotLit: 导入所有子笔记和独立笔记, or start an import from Zotero. The imported file is a copy. Your edits to it never go back to Zotero, and later edits to the Zotero note reach it only when you re-import that note.

In a template, noteLink links to the imported file when one exists. Otherwise it gives a link that opens the note in Zotero. See Import Zotero notes.

Existing notes stay as they areCopy anchor link

Notes you already have don't change. A note with the managed markers keeps them, and an update still refreshes the text between them. To stop that, delete the two marker lines. See Literature notes and the managed region.

If you customized or duplicated the Default profile, its document now has no managed block. Updating an older note with markers then shows 属性已更新。配置方案文档没有托管块，因此笔记正文保持不变。 To keep refreshing that region, add a {% managed %} block to the profile document.

What's NewCopy anchor link

Annotation links open the annotation on any computerCopy anchor link

Every annotation ZotLit writes into a note now links to Zotero with a zotero://open link that names the annotation. The link works on every computer where you open the vault. Before, the link pointed to a local file and worked only where that file path existed. See Zotero open links.

When you click the link on a computer that has the PDF, the PDF opens in Obsidian's PDF reader with the annotation selected. Otherwise, Zotero opens it. To send these links to Zotero every time, turn off 在 ZotLit 阅读器中打开标注链接 under Settings > ZotLit > 阅读器. It is on by default. See Open a PDF from a link in a note.

Hover over an annotation link in Live Preview, Source mode, or Reading view to see a popover. It shows the quote, your comment, the page, and the highlight color. For an image or ink annotation, it shows the image. The 悬停行为 setting under Settings > ZotLit > 引文 controls this popover. Set it to 关闭 to turn it off.

The default annotation template has a new layout. The paper's citation now follows the quote, and the page label is the link. When the annotation has no page label, the link reads "[Zotero]". If you use the default template, annotations you insert from now on look different from your older ones. Custom templates keep their output. See Default templates.

A new 批注引用 setting under Settings > ZotLit > 引文 is off by default. Turn it on to count an annotation link as a citation of its paper. The paper then appears in the 参考文献 sidebar and the other citation features. See How in-text citation rendering and navigation work.

Show any paper in the Zotero library viewCopy anchor link

在 Zotero 文库中显示 now appears wherever ZotLit shows a paper. You find it on rows in the 参考文献 sidebar and in the 被引用 toolbar. It is also in the citation hover popover, in the graph menu of a cited work, and in a literature note's file menu. The new ZotLit: 在 Zotero 文库中显示条目 command does the same. Before, only Alt+Enter in the quick switcher did this. See Show a paper in the library.

The Library View clears its search and filters so nothing hides the paper, then flashes the paper's row. When the paper is in none of your libraries, the view keeps your search and filters and shows 在你的文库中找不到该 Zotero 条目。

Templates have a new zt.librarylink variable. It gives an obsidian://zotlit/show-in-library link that works on every device you sync the vault to. It is available on the note's item, its parent item, and its related items. See Template data.

Other improvementsCopy anchor link

• The item details in the Library View now show and hide on request. Use the 显示条目详情 button at the end of the search row, press Space on a row, or select 关闭 on the card. ZotLit remembers your choice. A click or an arrow key now only selects a row, so the selection responds at once. With no paper selected, the details show counts for the library or collection. On a narrow pane, the details sit under the list at full width, and you can resize them. You can collapse and resize the library tree, and wide details use two columns. See Read a paper's Reading Card.
• Filter expression editors now color the code and put a wavy underline under errors. This covers the Query View filter, Formula fields, and Profile match. They also complete field and function names (press Tab or Enter to accept). A hint shows a function's arguments as you type. See Filter the rows.
• The citation suggester and ZotLit: 插入 Markdown 引用 list the papers the note already cites first when you have typed nothing yet. Those rows show 已在本笔记中引用. See Insert citations.
• The welcome checklist has an optional, recommended step: 安装 ZotLit Companion. The step shows 已安装 once Zotero has the Companion. See Install ZotLit Companion.
• The page chip on a card in the Zotero 标注 view opens the PDF in Obsidian when the file is on this computer, and in Zotero otherwise. Before, it always opened Zotero. See Open an item's PDF in Obsidian.
• An annotation you insert from the Zotero 标注 view, by the card menu or by drag, now gets correct spacing. It gets a space before it after a word and a space after it before the next word. It gets no space before closing punctuation. Stray line breaks around a one-line quote are removed.
• ZotLit: 创建或更新所有文献笔记 is much faster in large libraries. For 10,000 new notes, the confirmation appears in about one second instead of about ten.
• Notes with many citations open and update faster.

Bug FixesCopy anchor link

• If you pressed Enter or clicked right after typing in a picker, the picker could act on an earlier search. This affected the quick switcher, ZotLit: 插入 Markdown 引用, the item chooser, and the citation suggester. It could insert the wrong citation or create the wrong note. Now Enter waits for the results of what you typed.
• A search for an eight-letter word, such as "thinking" or "kahneman", found nothing. Now it finds the matches.
• The Zotero 标注 view could stay on 加载中… after you switched to a paper whose annotations load slowly. It stayed there until you clicked into it. Now the cards load.
• A citation inside the prefix or suffix of another citation, such as [@a with [[Note]]], broke the Pandoc export of the outer citation. Now the inner citation exports as text, and its work still appears in the bibliography. See Export a note with citations.
• After a reload, a restored PDF tab could count as a read with no page turn. The paper then moved up in Recent and in Zotero's Recently Read list. Now only real page turns count. See Keep the read time in Zotero.
• If you turned ZotLit off and on quickly, commands could go missing or a start-up error notice could appear. Now ZotLit starts cleanly.
• In the Query View filter, property names shrank to an icon or were cut off, and tag chips broke mid-word. Now they show in full.
• Keyboard fixes:
  • Escape that cancels a resize no longer clears the selection.
  • In the item menu of a list cell, Delete no longer removes the item, and Escape closes only the menu.
  • Escape closes the tag editor.
  • Undo works in the match expression field.
• Fast typing in a filter expression could move focus away and drop keys. Now every key reaches the field.

This beta introduces the Library View to browse your Zotero library directly in Obsidian. It turns ZotLit Query into interactive tables and note blocks. You can also track reading status in place and view recent papers ranked by active research.

HighlightsCopy anchor link

Browse your Zotero library directly in ObsidianCopy anchor link

The Library View is a visual library browser directly inside Obsidian. It opens with ZotLit: 打开 Zotero 文库 or from the ribbon. It reads directly from your local Zotero database, so it works without the ZotLit Companion or a local server.

The sidebar tree shows your collections, subcollections, and paper counts. Quick filters let you focus on 未读, 有批注, papers with literature notes, or papers with PDFs. You can also filter papers by tags.

The papers list shows two-line cards with reading status indicators and citation keys. Press the arrow keys to browse, or drag a row into an open note to insert a citation. On the right, the Reading Card shows metadata, an abstract, and expandable annotation previews. See Browse your library in the Library View for a full walkthrough.

To track reading status, select 另存为查询文件… and switch the view to the Table layout. Add a literature note property such as reading-status in 属性, then select a cell to change the value without opening the note. Checkboxes toggle with one click, lists edit as chips, and dates open pickers. A paper without a note shows 无笔记; type a value there to create the note and save the value. Values live in your notes, so Obsidian's Properties panel and Bases show the same values. See Track reading status in the Query View.

Breaking ChangesCopy anchor link

Default literature notes display annotations in a Query BlockCopy anchor link

The default note template now embeds an interactive query block instead of a static markdown list.

Updating an existing default note replaces its static annotation list with a query block. Annotations appear as interactive cards that reflect live changes in Zotero.

To keep a static markdown list instead, use a custom template with an annotation loop. See Literature notes and the managed region and Customize a template.

What's NewCopy anchor link

Interactive Query Files and embedded Query BlocksCopy anchor link

You can now create standalone .zotquery query files and embed query blocks in any note. Create a new file with ZotLit: 新建查询文件 or from an empty tab.

Each query view can display as a Table, Cards, a List, or Annotations. In the Table layout, drag column headers to reorder or resize columns. Expand rows to inspect attached files and child notes, or click links to open PDFs directly.

The visual filter editor supports nested condition groups with drag-and-drop reordering. The toolbar includes sorting, grouping, search, and export to CSV or TSV. You can also add custom Formula properties and set custom display names for columns.

See Query files and query blocks and Use query files for details.

Recent papers follow your active researchCopy anchor link

Recent lists now put the papers you worked on last at the top. Opening a literature note, reading a PDF, citing a paper, and editing notes or annotations all count.

The Library View explains each paper's position with a reason and relative time. The Quick Switcher, Citation Suggester, and Template Workbench use this same order.

The Library View's 未读 filter leaves out papers with a Zotero read time. With Write Authorization enabled, reading a PDF in Obsidian updates Zotero's Recently Read list.

See How Recent orders papers for details.

Sidebar Annotation View built on the Query View engineCopy anchor link

The sidebar Zotero 标注 view now runs on the Query View engine. You can save the sidebar view and its active filters directly as a .zotquery file.

Newly created annotations appear on screen immediately without waiting for database sync. The view shows clear diagnostic messages if database reads fail or a filter has an error.

See Use the annotation view for more information.

Other improvementsCopy anchor link

• In the Quick Switcher, press Alt+Enter on a result to reveal and select that paper in the Library View.
• Color and tag filter buttons in the annotation view remain visible when empty. A tooltip explains why the filter is disabled.
• ZotLit Query introduces firstAuthor for the primary creator and supports querying parent attachment fields for annotations.
• Export to PDF prints query view rows cleanly without toolbar cutoffs.

Bug FixesCopy anchor link

ConnectionsCopy anchor link

• When another local service used Zotero's HTTP port, the connection probe previously failed with an unhelpful error. It now detects that Zotero is unreachable and prompts you to open Zotero and check settings.

Notes and annotationsCopy anchor link

• Inserting an annotation into a note open in Reading view previously wrote markdown into the hidden source editor. ZotLit now requires an active editor tab and alerts you if the note is in Reading view.

This beta adds an experimental command-line interface to query your Zotero library, moves database reads into the background so Obsidian stays responsive, and introduces Chinese word search for titles.

What's NewCopy anchor link

Query your Zotero library from the command lineCopy anchor link

This beta introduces an experimental command-line interface to query your Zotero library.

Run queries over your Zotero library from the Obsidian CLI with zotlit:query. Search, filter, group, and project fields from your items, file attachments, and annotations in one command.

Four companion commands complete the toolkit. zotlit:query-values discovers exact collection and tag names. zotlit:query-schema returns the schema of every queryable field. zotlit:query-guide prints the built-in usage guide. zotlit:query-cancel cancels a running export.

Useful for checking reading status, finding missing PDF files, counting papers by year or tag, and exporting clean JSON for research scripts or AI agents. Because the feature is experimental, its parameters and output formats may change before the stable release. See How ZotLit Query works and Query your Zotero library for full guidance and examples.

Smooth background library readsCopy anchor link

Zotero database reads, search indexing, and citation lookups now run in the background. Obsidian stays completely responsive during large library refreshes.

Typing in the citation suggester and search pickers never freezes or hitches your editor, even in libraries with tens of thousands of items.

Chinese word searchCopy anchor link

A new 中文分词器 option is available under Settings > ZotLit > Zotero. One-click install splits Chinese titles into words, so searching for a word finds the paper even when the term sits in the middle of a Chinese title.

Reorganized Zotero settingsCopy anchor link

The Zotero settings page now follows research tasks: Zotero database, 文库, 与 Zotero 同步, 编辑, and 搜索. Advanced connection and database override options moved to a dedicated Zotero 位置 sub-page.

The page shows clear live status for the local server and links directly to its configuration.

Other improvementsCopy anchor link

• ZotLit entries in file menus and tab "More options" menus now sit in dedicated groups beside Obsidian's own entries, rather than clustering at the bottom below "Delete".
• Item search modals and Quick Switcher open with their rows ready or show a clean loading message (正在加载 Zotero 条目…), so the layout never pops in empty.

Bug FixesCopy anchor link

Annotation view and PDF editingCopy anchor link

• The annotation card list now scrolls completely clear of the bottom status bar, so the last card is never hidden behind it.
• When scrolling down, the top of the annotation list fades smoothly under the filter bar instead of cutting off abruptly.
• Confirmed annotation edits, color changes, and deletions remain protected and are not interrupted or overwritten by background database refreshes.

CitationsCopy anchor link

• Wikilink citations with fragments, such as [[@key#fragment]], in note previews and keyless items now resolve to their correct literature note paths.
• In-memory citation text for closed notes is released five minutes after closing, preventing memory buildup during long writing sessions.
• Pandoc export no longer requires citation key resolution when an exported note contains no literal citation keys.

Batch windowsCopy anchor link

• Batch confirmation windows for updating or importing notes across a library mount list rows on demand when you expand a group. Obsidian stays responsive even with libraries of tens of thousands of items.

This beta shows a literature note's full path while you edit its profile, and fixes many problems found in the Template Workbench, citations, and Word export.

What's NewCopy anchor link

Note pathCopy anchor link

The 名称和文件夹 tab of the Template Workbench now shows one 笔记路径 group. It holds the 文献笔记文件夹, the 笔记名称模板, and a 预览 of the full vault path the note gets. A slash (/) in the note name makes a subfolder. See Template Workbench View and Customize a template.

添加配置方案 on Settings > ZotLit > 文献笔记配置方案 now needs only a valid name that no other profile uses. The folder is optional; leave it empty to use the Default profile's folder. Before, ZotLit refused a new profile unless its folder, citation style, or note look was different. See Use a different template for different notes.

When you switch a note to another profile, or delete a profile and its notes move, each note now keeps its subfolders under the new folder. For example, literatures/2024/Smith2020.md moves to books/2024/Smith2020.md. Before, the note moved to the top of the new folder.

Other improvementsCopy anchor link

• The search box of ZotLit: 打开文献笔记快速切换器 reads 按标题、作者、年份或文献引用标识（citation key）搜索…, so you know what you can search by.
• The notice that confirms Zotero editing is on now closes after 3 seconds. Before, it covered the top of the annotation view for 10 seconds.
• The export dialog shows the destination in a readable form. A destination in your vault shows its path in the vault and the vault name; a destination in your home folder shows a short path.

Bug FixesCopy anchor link

Template WorkbenchCopy anchor link

• A property rule such as zt.creators | map: "fullName", or a note name with quotes, : , - , or a leading *, &, or !, could change meaning when you typed it into a Workbench pane, or break the profile so that it stopped working. Text you type now saves exactly as you typed it.
• While the profile had an error, 移除属性 and 更改格式并重置值 on the 属性 tab looked like they worked but changed nothing. The tab now tells you to fix the error first and stops list changes until you do. You can still edit the rules to make the repair. 查看问题 goes to the error, and undo restores the last working version. See Configure frontmatter properties.
• Folded rows on the 属性 tab showed broken summaries for a profile saved with Windows line endings. They now show the rule correctly.
• ZotLit: Customize this note's template showed the Workbench in the main window for a moment before it moved to its own window. It now opens in its own window directly.
• A reopened Workbench went back to the 笔记 tab. It now returns to the tab you were on, such as 标注, 名称和文件夹, or 源码.

CitationsCopy anchor link

• With 将引用作为链接打开 off, a plain click on a formatted citation did not put the cursor in it. The click now shows the citation's source text with the cursor where you clicked. Ctrl-click or Command-click still opens the cited literature note.
• [[@key]] was read as a citation, both in the editor and in the note's references. It is now an ordinary wikilink.
• An inserted bracketed citation such as [@key] got a space after it, so punctuation could not follow it directly. It now gets no space.
• Editing the locator after a citation key, as in [@key, p. 5], opened the citation suggester, and choosing a result replaced the locator. The suggester now stays closed while you edit a locator.

Notes and annotationsCopy anchor link

• Live note updates moved your reading position. The note now stays where you were reading.
• ZotLit: 更新文献笔记 and ZotLit: 更新文献笔记元数据 were not available while the cursor was in the note title or in Properties. They now work from anywhere in the note.
• A dragged annotation dropped at the end of a sentence joined that line. It now goes in as a block of its own. A drop on the empty last line of a note now inserts the annotation, and a drop with no target note tells you so. See Use the annotation view.
• In Live Preview, the %%/zt-managed%% closing marker was hidden inside the last callout of the note. It now stays outside the callout.
• The 被引用 view showed zero counts when no literature note was open. It now shows counts only for a literature note.

ExportCopy anchor link

• Exporting to Word now handles three things correctly. See Export a note with citations.
  • A callout showed its raw [!type] text. It now becomes a quote with a bold title.
  • A quote directly under a line of text became plain text. It now stays a quote.
  • The reference list had no heading. It now has one in the language of the citation style. The note's reference-section-title property sets a different heading.

Welcome viewCopy anchor link

• The folder, ZotLit Companion, and first-note steps stayed to-do after you completed them. They now show as done, and the Companion step stops offering the install once the Companion is installed.
• ZotLit: 打开欢迎视图 opened in place of the active note, so going back skipped that note. It now opens in a new tab beside it.
• Choosing a result in the literature note search from the Welcome view opened a second copy of a note that was already open. It now switches to the open note. Modifier keys still open the note in a new pane.

This beta lets you read and annotate your Zotero PDFs in Obsidian, next to the note you are writing, and every mark you make is saved in Zotero.

HighlightsCopy anchor link

Read and annotate your Zotero PDFs in ObsidianCopy anchor link

A Zotero item's PDF now opens in an Obsidian tab beside the note you are writing, so you can read and mark up a paper without switching to Zotero. The PDF stays in Zotero's storage, outside your vault; opening it there needs Obsidian 1.14.2 or later. The highlights and notes you made in Zotero are already on the page, in their Zotero colors. With Zotero 10 or later, what you mark in Obsidian is saved to Zotero, so it syncs and shows in Zotero's reader like any other annotation.

You can open a PDF from several places:

• From a literature note, run ZotLit: 打开 PDF, or choose it from the note's tab menu.
• In ZotLit: 打开文献笔记快速切换器, press Shift+Enter on a result.
• In Zotero, choose 在 Obsidian 中打开 PDF from an item's context menu, or 在 Obsidian 中打开 PDF from the page menu of Zotero's reader. Both need the updated ZotLit Companion.
• Click a file link in a note. The PDF opens on the right page, with the linked annotation selected.

The Zotero 标注 view comes forward in the sidebar with the PDF. To keep your sidebar as it is, turn off Settings > ZotLit > 阅读器 > 显示标注视图. To send file links to your system app again, turn off 在 Obsidian 中打开 PDF 文件链接 on the same page. Only PDFs open in Obsidian; EPUBs and web snapshots stay in Zotero. Open an item's PDF in Obsidian lists every way in.

The toolbar beside the page creates the same annotations as Zotero's reader: 高亮, 下划线, 添加笔记, 添加文本 for text typed onto the page, 选择区域 to capture a figure or table, and 绘图 for freehand strokes. Each tool keeps the color you last chose for it, in every PDF.

Select a mark to change its color, comment, or tags. The comment editor takes bold, italic, subscript, and superscript, as in Zotero. When the PDF's text came out wrong, for example with broken ligatures, 编辑引用文本 on the annotation's card corrects the quoted text. You can drag a mark to move or resize it, and delete an annotation after a confirmation. While the PDF is open, Ctrl+Z (Windows) or Command+Z (macOS) undoes your last annotation change, and redo applies it again. Edit PDF annotations in Obsidian covers each tool and key.

Reading needs no permission. Editing needs four things:

• Zotero 10 or later. With Zotero 9, the PDF opens and shows its annotations, but changes cannot be saved from Obsidian, and ZotLit tells you to update Zotero.
• Zotero is running on the same computer.
• In Zotero, Allow other applications on this computer to communicate with Zotero is on, under Settings → Advanced. ZotLit tells you when it is off.
• ZotLit has your permission, given once. Select 允许编辑 in the annotation view, or 允许编辑 on the Zotero 编辑 row under Settings > ZotLit > Zotero. When Zotero asks, choose Always Allow. Allow alone leaves editing off.

When an annotation changed in Zotero while you were editing it in Obsidian, the card shows 已在 Zotero 中更改 with both versions, and you choose which one to keep. Annotations that Zotero will not let you change are locked in Obsidian too. Examples are annotations Zotero imported from the PDF file itself, and in a group library, annotations another member made. A lock icon on the card gives the reason.

Edit a given annotation in one app at a time, and let each change save before you switch. A known Zotero issue can make one edit silently overwrite the other when both apps change the same annotation.

Breaking ChangesCopy anchor link

Exports cite with the note's own styleCopy anchor link

ZotLit: 导出带引文的笔记 and native Pandoc runs now format citations in the style the note uses in Obsidian. That is the note's own zotlit-csl property, the style of an imported note's profile, or your 参考文献样式. The export dialog says where the style comes from, and the notice at the end names the style it used.

The built-in export used to fall back to a bundled style when Zotero could not supply the one you chose. It now stops and tells you, so a document never comes out in a style you did not pick. Install the style in Zotero, or choose another one in the dialog.

If you run Pandoc yourself with ZotLit's integration files, save them again from this version. The files from earlier versions no longer work with this release. See Export a note with citations and Export with native Pandoc.

What's NewCopy anchor link

Annotation viewCopy anchor link

• The view keeps the follow mode you choose, 活动标签页, Zotero 阅读器, or 已固定, until you change it. When its source has nothing to show, the view says so in place.
• Select several cards with Ctrl-click or Command-click, Shift-click, or Ctrl+A / Command+A. Then delete them, recolor them with the keys 1 to 8, or copy their text together. One undo reverses the whole group.
• 插入到笔记 in a card's menu inserts the annotation at the cursor in your note, the same text a drag leaves, so you can insert from the keyboard as well.
• 打开 PDF in the view's menu opens the attachment on screen in Obsidian.
• 按标签筛选 and 按颜色筛选 open as small popovers, so the filters no longer push the list down.
• Edit an annotation's tags on its card or in the PDF popup, then select 保存标签.
• Image and ink annotations show their picture on the card and insert into notes with both PDF readers closed. The picture updates after you edit the annotation. See Excerpt images.

Use the annotation view has the full guide.

ZotLit CompanionCopy anchor link

• 笔记打开位置, in the 在 Obsidian 中打开 section of the ZotLit pane in Zotero's settings, chooses where notes opened from Zotero's menus appear: 当前标签页, 新标签页, 新标签页组, or 新窗口.
• obsidian://zotlit/ links take the same choice as a paneType parameter: tab, split, or window. See Where the link opens.

Bug FixesCopy anchor link

• In Zotero, right-clicking a PDF attachment opened an empty ZotLit submenu. The submenu is now dimmed when none of its entries apply.
• Converting 2.1 template files: when moving the old files to the trash failed, the conversion is still kept, and ZotLit names the files left behind and tries the cleanup again.
• When ZotLit refuses a template conversion, it now names only the files you need to edit.
• The reminder shown after you postpone the template conversion is shorter.

ZotLit 2.2 gives a literature note template one document of its own, adds a workbench to edit it inside Obsidian, and draws your citations in the graph view.

HighlightsCopy anchor link

Citations in the graph viewCopy anchor link

Your citations now appear in Obsidian's graph. A note gains an edge to every work it cites, so literature notes stop floating unconnected and two notes that cite the same paper meet at its node. Where no literature note exists yet, the work appears as a dimmed Cited Work Node.

This is on as soon as you update. Every ordinary graph starts drawing citation edges and Cited Work Nodes, so your graph is busier than it was. 在关系图谱中显示引用 under Settings > ZotLit > 引文 turns it off again.

Six rows in the graph's own controls decide what each graph draws, built into the native Filters and Display sections and saved per graph like the native rows:

• Under Filters: Pandoc 引用 and Wiki 链接引用, both on, and 仅显示引用相关节点, off.
• Under Display: 作者和标题标签, 为引用连线着色, and 引用弹出框, all off.

Wiki 链接引用 appears only while the vault-wide wikilink citation setting is on. Restore default settings in the graph returns all six to their defaults along with the native options.

Literature notes keep the node colors Obsidian gives them. A Cited Work Node takes a dimmed color of its own, and citation edges take theirs only while 为引用连线着色 is on. Your own color groups still win, and one press of 添加文献笔记分组 in the Groups section colors every literature note without a search query. All three colors have theme hooks; see Theme hooks.

作者和标题标签 writes the authors and the year above each work, with the short title dimmer underneath. Zooming in brings the titles out, and hovering shows one at any zoom. The graph's search box still matches your files, not the labels on screen.

Hover needs the per-graph 引用弹出框 row, which starts off. With it on, hovering a literature note or a cited work follows your Hover Action setting, and Settings > ZotLit > 引文 > 需要按住修饰键 adds a 关系图谱 row so the graph alone requires a held modifier key. A work with no literature note, and a note nothing cites, now show the formatted entry in the popover instead of Obsidian's page preview.

Select a Cited Work Node to create its literature note from the profile and open it; the key that matches one item becomes the note node, with the same edges. Right-click one for 创建文献笔记, 在 Zotero 中打开, and 复制文献引用标识（citation key）. A key that matches several items keeps its dimmed node.

ZotLit: 打开引用关系图谱 and ZotLit: 打开局部引用关系图谱 open the graph arranged for reading as a research map: citation edges in, every node except your literature notes, cited works, and the notes that cite them hidden, arrows on, labels and the popover on, and the literature notes group added. A global graph keeps one set of options for the whole vault, so the first command saves that arrangement as your graph settings. The local command needs an open note.

If a command opens nothing, ZotLit says why: the Graph core plugin is off, the citations switch is off, or the citation graph is unavailable. Explore citations in the graph view is the full guide.

Literature note profilesCopy anchor link

2.1 built a literature note from separate files: a note file, a managed-region file, a filename file, an annotation file, and a frontmatter field list that lived in settings. 2.2 puts the whole note into one Markdown document per profile. Each zotlit-profile.<slug>.md in your template folder holds the note name, the note folder, the properties, the note body, and the annotation format together.

Two companions complete the set. zotlit-citation.md holds the text of every inserted citation, once for the whole vault, and each zotlit-partial.<name>.md holds template text that several profiles share. Profile document gives the format of all three.

Settings > ZotLit > 文献笔记配置方案 is the new home of all of this. The 默认 row is your default layout; 添加配置方案 creates another profile, and 导入配置方案… reads one in from a file or the clipboard. A profile's own row offers 编辑配置方案 and a 更多操作 menu with 复制配置方案, 分享…, and 删除配置方案. A profile's match is edited on the workbench's 匹配 tab.

Below the profiles sits the 片段 list, with 添加片段 and 打开片段. A document ZotLit cannot read, or one whose ID collides with another profile's, is listed under 已排除的文档 instead of being used.

引文文本 under Settings > ZotLit > 引文 opens the citation document, and its 重置为默认值 button returns it to the built-in text once you have changed it.

A profile can also select itself. A Profile Match tests an item's library, item type, tags, or collections, and every new note that fits uses that profile. A profile without a Match stays manual. See Profile Match, and Use a different template for different notes for the steps from an empty profile to a matched one.

Every note records the profile that made it, so a later update uses the same template. ZotLit: 切换文献笔记配置方案 moves a note, and the imported notes that follow it, onto another profile.

Profiles explains how ZotLit picks one and how a note keeps it, How templates work covers the three kinds of document, and converting 2.1 template files the upgrade.

The Template WorkbenchCopy anchor link

Your templates have a view of their own now, with the fields beside the editor and the resulting note on the other side. ZotLit: Switch to template workbench view opens the document in your active note, and ZotLit: 打开模板工作台 opens all three panes together, in a window of their own when the editor would otherwise share one. From a literature note, ZotLit: Customize this note's template opens the profile that made it with that paper already selected.

The layout has three columns. The 模板字段 pane lists the Zotero data a template can read, the middle column edits the document, and the 笔记预览 pane shows the note that comes out. The panes are linked through Obsidian's own linked tabs, so choosing a paper or an annotation in one follows in the others.

The preview refreshes as you type. Its pane menu switches between 预览为新笔记, 预览为更新后的笔记, and 仅预览更新的部分, with 显示 Markdown to read the raw output. When you arrive from a literature note, the top bar names that note and offers 更新此笔记 to apply the change there at once.

Repeated text becomes a partial in one step. Select it, then choose 提取为片段…. 新建片段… starts one from scratch, the 片段 menu lists every partial in the vault, and 以 Markdown 打开 opens the same document in Obsidian's own editor.

Template Workbench View describes every way in, Customize a template walks through the profile, the citation text, and partials, and Edit a profile as Markdown is the route for anyone who would rather type the document.

Inside the Template Workbench ViewCopy anchor link

The editor is tabbed by part of the note: 笔记, 属性, 标注, 名称和文件夹, 匹配, and 配置方案. 源码 shows the whole document as source when you want it that way. Every edit saves as you go.

The editor knows the document's language. Liquid templates get their tags, variables, and filters highlighted, with the YAML manifest and the Markdown markers styled apart from the body. Eta templates pair tags as you type and gain the same suggestions and hover; the JavaScript 模板 gate governs rendering, not editing. Typing a field or a partial name offers what is available and what it holds.

When something fails, 问题 sits under the editor with what went wrong, which part of the document it came from, and the actions to reach it, including 复制错误报告 when you want to ask for help. Collect debug logs says what that report carries.

Properties covers the properties tab, and Template Workbench View the tabs, the languages, and the panes. The workbench view is part of the desktop app.

Breaking ChangesCopy anchor link

Four changes alter what you already have. Read them before you upgrade.

2.1 template files give way to documentsCopy anchor link

Nothing converts on its own. Your zotlit-note.liquid.md, zotlit-content.liquid.md, zotlit-filename.liquid.md, zotlit-annotation.liquid.md, the two citation files, and any file that served as a partial keep loading and rendering until you convert them. The Welcome view offers 转换文献笔记模板 once after the update, and settings repeat it with 查看转换. One press folds the note, managed-region, filename, and annotation files into zotlit-profile.default.md, the two citation files into zotlit-citation.md, and every remaining file into its own partial. ZotLit verifies byte-identical output before it writes anything, then moves the old files to Obsidian's configured trash. The pass needs one item from your Zotero library to verify against, and an annotation as well if you customized the annotation file.

Two things follow if you stay on the old files. Their settings rows are gone, so the frontmatter field list has no editor in the app, and a note cannot use a profile of your own until the conversion has run: ZotLit declines the note and asks you to convert the legacy templates first. The Profiles page shows no Add and no Import until the conversion has run, and every profile file action stays disabled; the quick-switch picker can still make a profile if you need one. Your default literature notes keep working exactly as they did.

If your two citation files use different languages, the fold is Liquid, the Eta file stays where it is, and ZotLit names the files that no longer affect citations.

Converting 2.1 template files has the steps and what each file becomes.

Export with citations stops on an unknown or ambiguous keyCopy anchor link

ZotLit: 导出带引文的笔记 now reads your note the way Pandoc does, so literal @citation-key text reaches the bibliography. A work you cite both by wikilink and by key gets one entry, nocite works, and a key inside code or behind an escape stays plain text.

The cost is that a key which matches no item in your library scope, or matches several, stops the whole export and names the keys. In 2.1 such a note exported with Pandoc's undefined-citation output and no reference list, which looked like success. Check the spelling in Zotero, or widen the library scope under Settings > ZotLit > Zotero. Export a note with citations covers the workflow.

The agent template commands are retiredCopy anchor link

Nine commands in ZotLit's obsidian CLI namespace now refuse every call and report the command as retired:

zotlit:template-schema, zotlit:template-render, zotlit:template-document-render, zotlit:template-source, zotlit:frontmatter-status, zotlit:frontmatter-eval, zotlit:frontmatter-set, zotlit:frontmatter-remove, zotlit:frontmatter-reorder.

An agent that wrote templates through them must move to zotlit:template-inspect, which reads a saved document and how current it is; zotlit:template-data, which lists fields with real values from an item; and zotlit:template-check, which renders every part and reports what fails. Frontmatter is edited in the profile document and checked with output=frontmatter. These are command line commands, not command palette entries. The Template Workbench CLI explains the loop, and the Template Workbench CLI reference lists every live command beside the retired one it replaces.

The settings tab is reorganizedCopy anchor link

• Maintenance is now Settings > ZotLit > 高级.
• The Database and Library pages merged into Settings > ZotLit > Zotero.
• The Live updates page became the 本地服务器 group on Settings > ZotLit > 高级, where 运行本地服务器 sits above 接收来自 Zotero 的更新.
• Note import is now Settings > ZotLit > 导入笔记.
• The Templates page is gone. 模板文件夹 and the 模板引擎 rows moved to Settings > ZotLit > 高级, and 引文文本 to Settings > ZotLit > 引文.
• 参考文献样式 moved to the main page, which now holds the default profile's rows.
• Auto-pair Eta tags has no toggle any more; the editor pairs tags as you type.

Row names are unchanged, so Obsidian's own settings search still finds a setting by the name you know. Where settings moved has the full table.

What's NewCopy anchor link

Imported notesCopy anchor link

Settings > ZotLit > 导入笔记 > 高亮映射

maps each Zotero highlight color on its own, to an emoji or to an HTML 标记, or to a 自定义 emoji you choose. See Import Zotero notes.

The emoji stay compatible with Obsidian 1.14's color highlights. With a custom mapping you can use more colors than native Obsidian offers, including Colorful Highlights.

Template data explorerCopy anchor link

The explorer is rebuilt on the workbench's own field browser. Fields are grouped into sections you can 展开所有分组 or 折叠所有分组, each row inserts itself with 插入字段 or copies it with 复制值, 复制路径, 复制输出, 复制（如果存在）, 复制循环, and 复制连接结果. The pane's menu saves the data as JSON: 导出所选论文数据 at a note root, 将模板数据保存为 JSON elsewhere. 选择条目 and 选择标注 switch which item or annotation the pane reads. See Explore template data.

Citations, references, and the suggesterCopy anchor link

• Hovering citations in a note retargets one popover instead of opening a card per citation, and the card follows the pointer from one citation to the next.
• Search results in the citation suggester read as one line: the venue in italics, and the volume and pages in their own form such as 3(2). A result from a group library is marked as such.
• When an imported note's profile or its citation style is unavailable, the References Sidebar says so and offers 切换配置方案… instead of dropping to a plain list.
• The suggester's footer now reads 插入替代引文 for the alternate form.
• A citation with a locator writes Pandoc's braced form, [@key, {p. 62}], in the raw source. The formatted text is unchanged.

See Insert citations and Review, copy, and troubleshoot references.

LaTeX citations in a templateCopy anchor link

tex_cite in Liquid, and texCite in Eta, write zt.citations as one LaTeX citation command, so a citation template reaches \cite{doe2024} or \autocite{doe2024} without a key loop of your own. The first item's prefix becomes the prenote, and its locator and suffix the postnote. See tex_cite and texCite.

One filter covers both formats Zotero Integration gave a command of its own, latex and biblatex. Migrate from Zotero Integration maps that plugin's Nunjucks templates, its persist blocks, and its citation formats onto profiles.

Batch update and importCopy anchor link

The confirmation for a vault-wide run now groups its rows by profile and says which items match no profile or several, which profiles are unavailable, and what happens to the notes you keep as they are. The import dialog names the notes that will arrive without a parent literature note before you confirm. See Keep notes up to date for a batch run, and Create and open literature notes for the profile a bulk run gives new notes.

Other improvementsCopy anchor link

• Links and menu commands from Zotero now name the profile they mean, so a note opens with the template you chose rather than the default. A profile ZotLit cannot find opens a prompt to pick one. See Protocol links.
• The Welcome view's settings link opens Settings > ZotLit > Zotero, and its folder picker explains how to navigate and choose.

Bug FixesCopy anchor link

• Fixed imported notes arriving with nothing but frontmatter (discussion #944). A Zotero child note created by another Zotero plugin or by automation, rather than typed in Zotero's own note editor, lost its entire body on import, with no warning. ZotLit only converted notes that carried Zotero's note-editor formatting marker. These notes now import with their content intact. Headings, paragraphs, bold text, and lists all become Markdown. Notes written in Zotero's note editor import exactly as before.
• Fixed the "Open literature note quick switcher" command showing only a title for most item types (discussion #939). The second line under each result, with authors, year, and where the work appeared, filled in for Journal Article items only. A Preprint, Book Section, Thesis, Report, Conference Paper, or Webpage showed a bare title, which made results hard to tell apart even though Zotero held the authors and ZotLit passed them to templates. Every item type now shows that second line, and the "where it appeared" part follows the item type, so a Preprint shows its repository such as arXiv and a Book shows its publisher. Custom item types and custom fields resolve too, and an item with no such field shows authors and year.
• Fixed the note commands in Zotero's item menu doing nothing on Zotero 10.0.2 (discussion #1064). Right-clicking an item and choosing "Open Literature Note in Obsidian" or "Create or Update Literature Notes" gave no feedback of any kind. Obsidian stayed closed and no error dialog appeared, because Zotero 10.0.2 tightened how add-ons may hand links to the operating system. Annotation sync and starting from the Obsidian side kept working throughout. Both commands open Obsidian again once you update the ZotLit companion add-on in Zotero to 2.1.4. The Obsidian plugin update alone does not fix this.

Bug FixesCopy anchor link

• Fixed Reading view flickering, jumping to the top, and resetting embedded content whenever any file in the vault changed (discussion #993). Toggling a checkbox in an Obsidian Base embedded in a note, or editing any other note, caused ZotLit to rerender every open Reading view. ZotLit now updates only the citations that actually changed. Scroll position, selected Base view, and embedded state all remain where you left them. Hover states and popovers on citations also stay open through Zotero database refreshes.
• Fixed dragging annotations from the Annotation Panel sometimes inserting only the raw highlight text instead of the rendered template output (discussion #966). The more plugins were loaded, the more often this happened. The drag handle now stays ready between preparations. When it is briefly unavailable (during a note switch or right after a drop), the annotation card dims its handle and cancels the drag with a notice instead of silently falling back to plain text.

Bug FixesCopy anchor link

• Fixed false "no matching item" errors that appeared after restarting Obsidian or after a period of inactivity. Citations that the item picker could still find would show a notice saying the citation key "matches no item in your Zotero library," and the error persisted until the next restart. ZotLit's citation-key lookup could fall out of sync on startup, and once broken it never recovered on its own. The lookup now stays consistent through startup and rebuilds itself after a failed read, so existing citations resolve correctly without a restart.
• Fixed citations flickering to raw @citekey text while typing. Each time Obsidian saved, the rendered citation text briefly disappeared before the fresh render arrived. The previous citation text now stays on screen while ZotLit re-renders, so citations remain stable during typing.
• Fixed citations and the References Sidebar flashing back to placeholder text when Zotero's database refreshed (for example, after editing an item in Zotero). ZotLit now keeps the previous content visible until the fresh data arrives, so a refresh that changes nothing produces no visible interruption.

Bug FixesCopy anchor link

• Fixed Pandoc rendering breaking after Live Updates ran once. Restarting Obsidian with Live Updates off was the only way to recover. Pandoc rendering now keeps working after Live Updates has run, with no restart needed.

This is the first stable release of the v2.1 citation workflow: the References Sidebar, in-text citation rendering, the Citation Popover, and the Cited By Sidebar, alongside Zotero 10 support and multi-library scope. The changes below cover what landed since beta.3; for the full tour, read the release post.

What's New since beta.3Copy anchor link

Pandoc engine performanceCopy anchor link

The built-in Pandoc engine now loads about three times faster: a 291 ms median load drops to 97 ms, and the JavaScript memory spike that came with each load is gone. If a cached engine binary is corrupted, ZotLit now detects it, clears it, and shows the install offer again.

Colored note-import highlightsCopy anchor link

Use colored highlight syntax, a new opt-in setting under Settings › Note import, converts highlights from Zotero note imports into emoji-based colored highlight syntax. It covers six highlight colors. A highlight with an unsupported color, or text that would break the syntax, stays as HTML instead. Annotation backlinks are preserved either way.

Bug Fixes since beta.3Copy anchor link

• Fixed recurring notices about database read-mode fallbacks. ZotLit now routes you to Companion installation or stale-data troubleshooting instead of repeating the notice.
• Fixed Pandoc export connecting to the wrong Zotero HTTP port when more than one Zotero instance is running. The port now resolves from the active profile.

HighlightsCopy anchor link

Zotero 10 supportCopy anchor link

ZotLit now supports Zotero 10 as well as Zotero 9.

Zotero 10 changed how it stores recent edits, so changes made while Zotero was open could stay invisible to ZotLit. The Companion now keeps the database current for ZotLit automatically. When you switch from Zotero to Obsidian, your changes are already there, whether or not live updates are enabled. A new 数据库状态 panel on the Zotero sidebar confirms that recent changes have reached the database and lets you trigger a manual update if something went wrong. See Fix Zotero changes that do not appear for details.

Library scopeCopy anchor link

ZotLit now works across several Zotero libraries at once. Library scope in Settings › ZotLit, decides which libraries item search, citation key resolution, and the library-wide commands cover. It replaces the old Default library setting.

Two modes:

• All libraries follows your Zotero database, so a group library you join later is in scope at once.
• Selected libraries stays exactly as you set it, and a group library you join later stays out until you add it.

One search now spans every library in scope, in a single relevance order. While more than one library can contribute, each result names the library its item comes from.

ZotLit: Create or update all literature notes and ZotLit: Import all child and standalone notes cover the whole scope too, and their confirmation groups rows by library. Menu entries and links from Zotero still target the exact library they came from, whether or not it is in your scope.

A group you leave keeps its place in Selected libraries, marked unavailable, so a temporary absence does not erase your choice. A library-wide run continues over the libraries that are available and states how many it skipped. See Settings › Library scope.

A scope ZotLit cannot read stays on disk as it is. ZotLit searches My Library alone, marks the setting with a warning, and clears it as soon as you set the scope again.

What the upgrade sets: upgrading selects Selected libraries with My Library alone, whatever library you had selected before, so your search scope stays as narrow as it was. Switch to All libraries, or add your group libraries, to search wider. A fresh installation starts at All libraries.

Citation keys that match several itemsCopy anchor link

One citation key can sit on two Zotero items. That happens with twins in a single library, and with the same key in two libraries you now have in scope. ZotLit used to take the first match it found. It now reports the ambiguity instead of choosing for you:

• Opening such a citation asks which item you mean, listing every candidate with its library and item key. The item you pick opens by its own identity.
• Inserting one is refused, with a notice asking you to change the key in Zotero. Inserted text carries the key alone, which would no longer name the item you picked.
• The References Sidebar reports a Reference Error listing the candidates, with its Open literature note action disabled. The citation popover names them too, and hover page preview shows nothing.
• Themes can style the state through the new zt-citation-key-ambiguous class. See Theme hooks.

To resolve one, give one of the items a different citation key in Zotero, or narrow your library scope to the library you meant.

What's NewCopy anchor link

Citation style and language per noteCopy anchor link

A note can now render its citations under its own style and language instead of the vault-wide selection. ZotLit: Set citation presentation, also in the note's More options menu, opens a dialog on what the note reads today and writes both choices in one pass.

The choices live in the note's own properties: zotlit-csl names a style installed in Zotero, and standard Pandoc lang names the document language. Removing a property returns that note to the vault selection.

In-text citations, the References Sidebar, the Citation Popover, the copied bibliography, and the built-in export all follow the note's own presentation.

Citation localeCopy anchor link

A new Citation locale setting under Settings › ZotLit › Citations sets the language for citation terms, dates, names, and sorting across the vault. It takes a language tag such as en-US, de, or zh-CN.

Leaving it empty keeps the language the selected style declares. See Settings › Citations.

Bug FixesCopy anchor link

• Fixed slow or broken database refreshes when the Zotero data directory sits on a different drive than the system temp folder, such as an external drive on macOS.
• Fixed dragging an annotation from the annotation view inserting the raw highlight text, or the annotation key for a sticky note, instead of the rendered annotation template. The insert only recovered after pressing Link to Zotero item again.

HighlightsCopy anchor link

Citation PopoverCopy anchor link

Hovering a citation now shows a popover with each cited item's full formatted bibliography entry, stacked in citation order for multi-item citations. Each entry carries action buttons to open the Literature Note, open the item in Zotero, or open its attachment. The popover works on literal Pandoc citations in Live Preview, Reading view, and Source mode, and on Literature Note wikilinks when wikilink citations are enabled.

A new Hover action setting under Settings › ZotLit › Citations › Hover controls what citation hover shows:

• Citation Popover (default): the popover described above.
• Page preview: the previous behavior, showing the Literature Note page preview under Obsidian's own Page Preview settings.
• Off: no ZotLit hover at all; native wikilink hover stays untouched.

Each mode has its own Require modifier key toggles per editing mode (Source mode requires Mod by default; Live Preview and Reading view do not). The toggles live on a sub-page under the Hover action setting.

Citation data commands for agentsCopy anchor link

Three new CLI commands, zotlit:cited-by, zotlit:references, and zotlit:citations-guide, let an AI agent query which notes cite a given item and what a document cites. Install the zotlit-citations skill for your agent to use this workflow.

What's NewCopy anchor link

Copy bibliographyCopy anchor link

The References Sidebar toolbar now offers a Copy bibliography action. One click copies the full reference list as both rich text and plain text. Emphasis, superscript, small caps, and DOI links survive a paste into Word or Google Docs. A destination that takes only plain text falls back to the text version, and the notice tells you which format was copied.

Note-class citation stylesCopy anchor link

Styles that use footnotes (such as Chicago full-note) now show numbered Entry Serials beside each citation inline and in the References Sidebar gutter, so you can see at a glance which reference number a citation carries.

Open citations as linksCopy anchor link

The Open Pandoc citations as links setting is now Open citations as links and covers both Pandoc citations and Literature Note wikilinks. It is off by default. While off, clicking a rendered citation in Live Preview places the cursor in its Markdown source (the widget collapses like clicked bold text). Mod+click still opens the Literature Note regardless of this setting.

Other improvementsCopy anchor link

• The References Sidebar toolbar now includes a Change citation and references style shortcut that opens the style picker in settings.
• Two-creator summaries (e.g. "Wang and Lee") now follow your locale's list formatting conventions.

Bug FixesCopy anchor link

• Fixed the Zotero database refreshing every few seconds even when nothing changed. A filesystem echo from the database clone triggered a self-feeding loop on APFS volumes.
• Fixed Mod+Enter in the note quick switcher not opening the note in a new pane. The keyboard shortcut was advertised but never registered. The modifier label now also shows the correct key per platform.
• Fixed Shift+Enter in the citation insert modal not inserting the secondary citation form. The keyboard shortcut was advertised but never registered.
• Fixed citations inside inline footnotes (^[...]) rendering at body text size instead of matching the footnote's superscript size.
• Fixed ^[...] being read as a citation cluster instead of an inline footnote. The bracket after a caret now starts an inline note as Pandoc expects.
• Fixed the References Sidebar engine banners overlapping with the reference list when the list was long enough to scroll.
• Fixed two items with the same filename colliding in the citation rendering. Each item now keeps its own bibliography entry and reference number, even when both are cited in the same document.

HighlightsCopy anchor link

Cited By SidebarCopy anchor link

A new sidebar view shows which notes in the vault cite the active Literature Note. Open it from the command palette via 'Open cited by'. Results are grouped by source file, each with an occurrence count, and every occurrence displays an excerpt from the citing note styled as a search-result card. Click any occurrence to jump to its location in the editor.

The toolbar offers four controls, consistent with the Backlinks panel:

• Show search filter opens a text field that narrows results by file path or excerpt content.
• Show more context switches between a compact 100-character excerpt and the full enclosing block (a list item or a section).
• Change sort order offers six modes: file name (A → Z, Z → A), modified time (new → old, old → new), and created time (new → old, old → new).
• Collapse results folds or unfolds all source groups at once.

What's NewCopy anchor link

• Filename templates can now include authors and authorsShort helper variables, consistent with the note template data.

HighlightsCopy anchor link

References SidebarCopy anchor link

A new sidebar view lists the citations in the active note as a formatted bibliography. Each entry shows the reference number and formatted text in the selected CSL style, with actions to open the Literature Note, open the item in Zotero, or open the attached PDF. Clicking the entry text walks through the citation's occurrences in the editor.

In-text citation renderingCopy anchor link

Literal citation clusters (e.g. [see @wang2020, p. 3; @lee2019]) now display as formatted text in both Live Preview and Reading view.

Literature Note wikilinks can also render as citations, sharing the same formatted display and numbering as literal citations. Turn this on with Wikilink citations in Settings > ZotLit > Citations — it is off by default.

The citation rendering also supports formatting in a CSL style you pick from Zotero's installed styles using Pandoc (setup in Settings > ZotLit > Citations).

Export a note with citationsCopy anchor link

A new command, ZotLit: Export note with citations, converts the active Markdown note to DOCX or HTML with a formatted bibliography. Choose the output format, CSL style, and destination in the export dialog. Citations resolve from the note's own links; no external Pandoc installation is required. See How to export a note with citations.

This feature is not finalized yet, but the command is available to test.

What's NewCopy anchor link

Citation key navigation and stylingCopy anchor link

Recognized citation keys in the editor are styled as links. An unresolved citation key (one that names no item in Zotero) is visually distinct from a resolved one. Click a citation key to open its Literature Note, or hover to see a page preview.

Rendered citations in Reading view are also navigable: a single-key citation opens the Literature Note on click, and a multi-key citation opens a menu listing each cited work. See How in-text citation rendering and navigation work.

Turn this off with Open Pandoc citations as links in Settings > ZotLit > Citations.

Citation key resolution from ZoteroCopy anchor link

Citation keys now resolve against Zotero's native citation keys instead of a frontmatter property. The Citation Key Property setting is retired and migrated automatically.

CSL style selectionCopy anchor link

The References Sidebar and in-text citation rendering use a CSL style you select from the styles Zotero has installed. The style picker appears in Settings > ZotLit > Citations. Leaving it unset or selecting a removed style falls back to a default.

Native Pandoc CLI workflowCopy anchor link

Convert a note with a standalone Pandoc installation, outside Obsidian, with Literature Note wikilinks converting to citations. A Save integration files action in the Citations settings page writes a Lua filter (zotlit-cite.lua) and a Pandoc defaults file (zotlit.yaml) matched to the installed plugin version; the Lua filter resolves each wikilink to its citation key through a new zotlit:resolve command, reachable from a CLI tool that supports Obsidian's command line interface (such as obsidian-cli).

Two more commands support this workflow: zotlit:pandoc-files returns the integration pair as JSON, and zotlit:pandoc-guide prints the setup and troubleshooting guide. A new zotlit-pandoc skill walks an AI agent through the same workflow: setup, refresh, running a native export, and diagnosing a failed run.

Theme supportCopy anchor link

• CSS classes are available on citation elements across editor and Reading view surfaces, documented in the theme hooks reference. Theme authors can style resolved, unresolved, pending, and rendered citation states.

This is a maintenance release. It brings the plugin's code in line with Obsidian's official developer guidelines and carries no changes to plugin behavior, settings, or commands.

For full v2 release details, see the v2 release blog.

This is the first public stable release of ZotLit v2. If you participated in the beta, thank you! Your feedback shaped every part of this release.

The changes below cover what landed since beta.4; for the full v2 feature set, see the release announcement.

Before you updateCopy anchor link

ZotLit needs Obsidian 1.13.4 or newer, and your installer version must also be 1.13.4 or newer. Obsidian's in-app update does not replace the installer. Check yours in Settings > About. If the installer is older, ZotLit does not load: Obsidian shows Failed to load plugin "zotlit", and the developer console shows a SyntaxError.

To fix this, download Obsidian from the download page and run the installer over your current installation. Nothing is deleted, and no notes are lost. See how to update the Obsidian installer and the beta.4 requirement note.

LicenseCopy anchor link

ZotLit is now licensed under AGPL-3.0-or-later (previously MIT). The change covers code ported from Zotero, which is itself AGPL-licensed. This does not affect how you use the plugin.

Breaking ChangesCopy anchor link

Citation Key Links is now opt-inCopy anchor link

Citation Key Links lets you click a [@citekey] reference in the editor to jump to its literature note. This feature is now an optional setting, disabled by default. If you used it during the beta or migrated from v1, it will remain enabled.

The feature resolves each citation key against Zotero's own native citation key, scoped to the citation library you have configured. If the matching item does not have a literature note yet, clicking the link creates the note and opens it.

What's NewCopy anchor link

Batch operations on libraries and collectionsCopy anchor link

You can now create or update literature notes and import Zotero notes across an entire library or a single collection (including subcollections), instead of selecting items one at a time. Right-click a library or collection in Zotero's sidebar to find 创建或更新文献笔记 and 导入子笔记与独立笔记 in the ZotLit submenu. The same actions are available as Obsidian commands and protocol links (update-all, import-all-notes).

Other improvementsCopy anchor link

• Settings actions in notices and the Welcome View now open directly to the relevant settings sub-page instead of dropping you at the tab root.
• The "Receive updates from Zotero" toggle now shows a hint linking to the install guide for ZotLit Companion, the Zotero add-on, when the Companion is not yet set up.

Breaking ChangesCopy anchor link

Obsidian version requirementCopy anchor link

ZotLit now requires Obsidian 1.13.4 or newer. This release also requires the newer Electron version bundled with the Obsidian installer. Updating Obsidian from inside the app is not enough: download and run the latest installer over your existing installation, then reopen Obsidian before you install or update ZotLit. See How to update the Obsidian installer and the Obsidian 1.13.4 release notes.

Citation template item.extraCopy anchor link

item.extra in citation templates now uses the same parsed ItemExtra shape as note templates. If a template reads the raw text, use item.extra.raw. See the template data reference.

What's NewCopy anchor link

Template WorkbenchCopy anchor link

The Template Workbench CLI adds Obsidian CLI commands for agents. An agent can inspect template state, render a template against Zotero data without changing your vault, and manage configured frontmatter fields.

Install the zotlit-template skill for your agent to use this workflow.

Managed frontmatterCopy anchor link

You can drag frontmatter fields into a new order. ZotLit uses that order when it creates a new literature note. Existing notes keep their current property order.

New template filtersCopy anchor link

The Liquid syntax now includes arr_prefix, arr_suffix, and arr_replace for changing every value in an array. The obsidian_tag filter converts text or Zotero tags into valid Obsidian tags. See the template syntax reference.

Copy Zotero keysCopy anchor link

Zotero context menus can copy the keys of selected items, attachments, notes, and annotations. Reader annotation menus also provide a copy action. In Obsidian, use ZotLit: Copy item key from a literature note's command or file menu.

Bug FixesCopy anchor link

• Fixed inconsistent item summaries between the Annotation View, Template Data Explorer, and Citation Suggester. These views now use the same title, creator, and date formatting.
• Attachments now copy from approved folders. Only Zotero storage, the annotation cache, and linked-attachment folders are approved by default. Add other folders under Settings > ZotLit > Attachments > Approved folders.
• Language packs now match the installed ZotLit version.

What's NewCopy anchor link

Initial Chinese (Simplified) language supportCopy anchor link

The plugin now ships with Chinese (Simplified) as a downloadable language pack. Open the Language Pack section in settings to install it.

backlink field on attachmentsCopy anchor link

Each attachment in zt.attachments and zt.parentAttachment now exposes a backlink field. It contains a zotero://open/... deep link that opens the attachment in Zotero's reader. This complements the existing backlink on the main item. See Template data reference.

Other improvementsCopy anchor link

• Confirmation dialogs now display correctly on Obsidian versions older than 1.13.0, where the built-in confirmation API is not available.

Breaking ChangesCopy anchor link

Citation output normalizationCopy anchor link

Rendered citation text inserted into notes is now trimmed and collapsed to a single inline line. The editor places a trailing space after the insert so the cursor lands ready to keep typing. Templates that intentionally produce multi-line citation output will see it flattened to one line when inserted.

Shift+Enter now selects the secondary citation format in the inline Citation Suggester, matching the behavior of the command-palette modal.

What's NewCopy anchor link

At Trigger for citationsCopy anchor link

An opt-in setting lets you type a bare @ to open the Citation Suggester instead of the default [@ trigger. Since the at-query has no closing bracket, use underscores in place of spaces (e.g. @cognitive_load). Enable it in the plugin settings under the citation section. See Insert citations for the full workflow.

Rich annotation cardsCopy anchor link

Annotation cards in the annotation view now render excerpts with inline formatting (bold, italic, subscript, superscript) and render Markdown comments through the same pipeline as the literature note. What you see in the card matches what the note template produces. Links in comments resolve against the literature note and open through the workspace.

Other improvementsCopy anchor link

• Context-menu labels in ZotLit Companion, the Zotero add-on, now say "Literature Note" instead of bare "note", and adopt Title Case to match Zotero's own menus.

Bug FixesCopy anchor link

• zt.parentItem.authorsShort and zt.parentItem.authors rendered empty in annotation templates, even though zt.parentItem.title worked. These fields now resolve correctly. zt.parentItem.backlink and zt.parentItem.weblink are also filled in.

• Updating only metadata on an item that had no literature note incorrectly created a full note from the template. Metadata-scoped updates now skip items without an existing note, as documented.

Breaking ChangesCopy anchor link

Per-device Zotero pathsCopy anchor link

The Zotero profile and data directory paths are now per device. If you sync your vault across machines, one computer's Zotero path no longer overwrites another's. An unset path means auto-detect; a path you set on one machine stays on that machine.

If the plugin cannot find your Zotero database on a new device, the Welcome View shows a notice pointing you to the locate action. See Use ZotLit on multiple devices.

If you previously set a custom Zotero profile or data directory path, you need to re-enter it once on each device after updating. The old synced values are not migrated.

What's NewCopy anchor link

zt.weblink template fieldCopy anchor link

A new template variable zt.weblink gives you the browsable Zotero web library URL for an item (e.g. https://www.zotero.org/yourname/items/ABC123), alongside the existing zt.backlink desktop deep link. It is available on the main item and on each entry in zt.relatedItems. Not available for accounts that have never synced. See Template data reference.

Bug FixesCopy anchor link

• Fixed the annotation view not following a Zotero reader opened in its own window (not a tab). Only tabbed readers were tracked before; standalone reader windows are now picked up on focus.

• Fixed batch imports and index builds slowing down when Obsidian's window was in the background or occluded.

What's NewCopy anchor link

Welcome viewCopy anchor link

A first-run landing surface appears on fresh installs and upgrades. It shows a live setup timeline with Zotero connection status, a note-folder picker, first-note search, and quick links to docs and community.

A resources strip on the setting tab (release notes, docs, help) is available on both Obsidian 1.13 and older versions.

Annotation view: search and filterCopy anchor link

A search row in the annotation view matches text, comment, tag, and page number. A filter bar with color swatches, a first-tag chip, and an inline tag drawer lets you narrow annotations without switching to Zotero. Cards default to collapsed for scanning, and the view reserves status-bar clearance so the list tail is never covered.

See Use the annotation view for the full workflow.

Note-status column in ZoteroCopy anchor link

ZotLit Companion, the Zotero add-on, now shows an extra column indicating which items have a corresponding literature note in Obsidian. This gives you an at-a-glance view of your note coverage from within Zotero.

v2 documentation siteCopy anchor link

The documentation site launched alongside this release, covering the full feature set: a tutorial, how-to guides, concept explanations, and a reference section for settings, commands, protocol links, and template syntax.

New guides: Suppress Zotero's security prompt, Collect debug logs, and a rewritten Migrate from v1.

Bug FixesCopy anchor link

• Fixed a crash on the Obsidian 1.13.3 installer at startup. Earlier installers and later versions were not affected.