v2.2.0latest

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 Open PDF file links in Obsidian and Open annotation links in ZotLit reader under Settings > ZotLit > Reader.

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: Update literature note 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: Import child notes from Zotero or ZotLit: Import all child and standalone notes, 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: Export note with citations 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 > Advanced, 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 location sub-page.
• Note import is now Settings > ZotLit > Imported notes, and the citation text is under Settings > ZotLit > Citations.

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: Open Zotero library 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 Unread, Annotated, 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 Show item details 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: Open PDF, with Shift+Enter in ZotLit: Open literature note quick switcher, 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 Allow editing 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: Create new query file, 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 No note. 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: Open citation graph and ZotLit: Open local citation graph open a graph arranged as a research map.

This is on by default. Turn it off with Show citations in graph view under Settings > ZotLit > Citations. 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 > Literature note profiles. 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: Switch literature note profile 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: Open template workbench opens all three panes.
• From a literature note, ZotLit: Customize this note's template opens its profile with that paper selected, and Update this note 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 Extract to partial….
• 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 Save as query file….
• The view follows the active tab or the Zotero reader, or stays pinned to one paper.
• Insert into note 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 Annotation citations under Settings > ZotLit > Citations to list the paper in the References and Cited by sidebars.

Turn on Show annotation links as citations, also under Settings > ZotLit > Citations 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 Annotation citations and Show formatted citations. See In-text citations.

Show in LibraryCopy Anchor Link

Show in Zotero library takes you to a paper in the Library View. Find it in the citation popover, the References and Cited by sidebars, the graph menu, a literature note's file menu, and as Alt+Enter in the quick switcher. The ZotLit: Show item in Zotero library 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: Insert Markdown citation 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.
• Chinese segmenter 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: Create or update all literature notes 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 > Imported notes > Highlight mappings

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

ZotLit CompanionCopy Anchor Link

• Open notes in 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: Open literature note quick switcher 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 Open citations as links 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: Update literature note 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 Cited by 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: Open welcome view 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.