Changelog

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 update

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.

License

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 Changes

Citation Key Links is now opt-in

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 reads the citation key from a frontmatter property on each literature note. If that property is not in your managed frontmatter fields, the plugin shows a notice explaining what to add.

What's New

Batch operations on libraries and collections

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 Create or Update Literature Notes and Import Child and Standalone Notes in the ZotLit submenu. The same actions are available as Obsidian commands and protocol links (update-all, import-all-notes).

Other improvements

• 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 companion install guide when the Zotero companion is not yet set up.

Breaking Changes

Obsidian version requirement

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.extra

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 New

Template Workbench

The Template Workbench 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 frontmatter

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 filters

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 keys

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 Fixes

• 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 New

Initial Chinese (Simplified) language support

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 attachments

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 improvements

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

Breaking Changes

Citation output normalization

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 New

At Trigger for citations

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 cards

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 improvements

• The Zotero companion's context-menu labels now say "Literature Note" instead of bare "note", and adopt Title Case to match Zotero's own menus.

Bug Fixes

• 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 Changes

Per-device Zotero paths

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 New

zt.weblink template field

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 Fixes

• 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 New

Welcome view

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 filter

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 Zotero

The Zotero companion 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 site

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 Fixes

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