Migrate from v1

ZotLit v2 replaces v1 in place. Settings migrate automatically on first load, but if you customized your Eta templates, they are not loaded until you rename them, update the data vocabulary, and enable the JavaScript Templates gate. Notes you created with v1 still appear in the index. Overwrite them when you want incremental body updates.

Install v2

After the upgrade, v1 is gone. If you need to consult the original documentation while you transition, the ZotLit v1 docs remain available.

Settings (automatic)

On first load after upgrading, ZotLit detects your v1 settings and migrates them automatically. No action is required for settings. The migration runs once and persists the result; write failures are logged but never block the plugin from loading.

What carries over:

• Your literature-note folder and template folder paths.
• Custom frontmatter fields, kept as JavaScript-language fields. Fields you never customized (still using v1 defaults) convert to Liquid.
• Embedded template sources (such as the filename template body) are not migrated because v2 uses a different data vocabulary (zt.* instead of v1's it.*). V2 reads templates from vault files instead.

Migrate templates

V2 template files use the naming pattern zotlit-<name>.(liquid|eta).md. V1 files used the zt- prefix (for example, zt-note.eta.md) and do not match the v2 pattern. Until you rename them, v2 does not load your custom templates and falls back to the built-in defaults.

V1 templates were written in Eta (JavaScript). In v2, Eta templates require the JavaScript Templates gate: a per-device opt-in stored outside synced settings, disabled by default. Until the gate is on:

• Eta template files (.eta.md) that match the v2 naming pattern are inert. A notice names the file and explains that JavaScript templates are disabled.
• JavaScript-language frontmatter fields are also inert. A notice lists the skipped fields when you update a note.

If you customized your Eta templates, these three steps are required to restore note generation:

1. Rename your template files to the v2 pattern (zt- to zotlit-, annots to content).
2. Replace it.* with zt.* throughout your templates.
3. Enable the JavaScript Templates gate on each device where you use ZotLit.

Follow Migrate v1 Eta templates for the full procedure, including field-by-field mappings and an optional Liquid conversion path.

Annotations in imported notes

When you import a Zotero note into your vault, v2 converts the annotation content already in the note directly. Highlights and underlines become inline marks with a zotero:// backlink, image excerpts become embeds, and your typed comments are kept as written. If you edited an annotation paragraph inside Zotero before importing, those edits are preserved. V1 re-rendered every annotation through the annotation template instead, which discarded in-place edits.

To restore v1-style rendering, open Settings → ZotLit → Note import and enable Render annotations from template. The toggle is off by default. When on, annotation paragraphs are re-rendered through your annotation template with data pulled fresh from Zotero.

Refresh v1 notes

V2 recognizes your existing literature notes by their zotero-key frontmatter value. They appear in the note index, and ZotLit: Update literature note metadata refreshes their frontmatter. However, v1 notes lack a managed region (the %%zt-managed%% markers that v2 uses to separate generated content from your writing), so incremental body updates cannot target them.

Adding the managed region is optional. You do not need to do it immediately or for every note. When you are ready:

Retired features

Two v1 workflows are not carried forward into v2.

Annotation merging. V1 could merge annotations from multiple PDF attachments or deduplicate them across updates. V2 does not include this workflow. Annotations are rendered per-attachment as they appear in Zotero.

Topic-based imports. V1 let you subscribe a note to a Zotero tag (#zt-topic/<name>) so that new items with that tag were automatically imported as literature notes. V2 does not include this workflow.

See also