Migrate from 2.1 templates

Use this guide when you are on ZotLit 2.1, your templates still work, and you want to know what the update changed.

What changed

In 2.1, a note's look was spread across separate files in the template folder, one file per part. In 2.2, the same look lives in a single profile document.

Nothing breaks on upgrade

Your 2.1 files keep loading and rendering after the update. ZotLit converts and moves nothing on its own, and your existing notes do not change. The conversion runs only when you start it.

Convert when you are ready

What the conversion does

ZotLit builds the new documents in memory and renders them against one item from your Zotero library. It compares the note, the update, the note name, the annotation, and both citation outputs against what your 2.1 files produce. It writes nothing unless every output matches byte for byte.

When the outputs match, ZotLit writes zotlit-profile.default.md, zotlit-citation.md, and one file per partial. It then moves your 2.1 files to Obsidian's configured trash. That trash is the only backup: ZotLit keeps no copy of the old files. If a file cannot be moved to the trash, the conversion still stands and the converted documents are active. A notice names the files left behind: The converted templates are active, but these old files could not be moved to trash: …. Retry cleanup from the welcome view. The Welcome view shows the same list, headed These old files could not be moved to trash and are still in your vault: Select Retry cleanup in the Welcome view to move them again. A file that still cannot be moved stays on the list.

One case keeps a file in place. If your two citation files use different languages, the citation text converts as Liquid and the Eta file stays where it is; ZotLit names the files through Legacy template files converted. The citation text converted as Liquid, so these Eta files stayed in place and no longer affect citations: …..

What is refused, and what you see

Every refusal happens before the first write, so your vault and your settings stay as they were. Each one reports a notice.

• A converted output that does not reproduce the old one. ZotLit kept the legacy templates unchanged because the converted … did not match. Edit these files and retry: …. This is the refusal you are most likely to meet, because it is what the byte check reports. The notice lists only the files you need to edit, and names the output that differed: create output, update output, filename output, annotation output, main citation output, or alternate citation output. Edit the 2.1 file behind that output so the converted form reproduces it, then select the button again.

• A layout ZotLit cannot convert automatically. ZotLit kept the legacy templates unchanged because this layout cannot be converted automatically. Edit these files and retry: …. The conversion handles only the shapes 2.1 shipped: one content insertion in the note file, and one language across the files. The notice lists only the files you need to edit. Edit them on disk to match, then select the button again. The notice also appears when an Eta file is involved and JavaScript templates is off; turn the gate on under Settings > ZotLit > Advanced > Template engine and try again.

• A frontmatter field written in JavaScript while the gate is off. Enable JavaScript Templates, then retry conversion; affected Managed Frontmatter fields: …. Turn on JavaScript templates under Settings > ZotLit > Advanced > Template engine, then select the button again. See Enable JavaScript templates.

• A field that fails to evaluate against the item ZotLit picked. Correct these Managed Frontmatter fields, then retry conversion: …. This release has no editor for the legacy field list, and a profile's edit actions stay disabled while the conversion is pending. The list lives in the plugin's saved settings file, under note.frontmatter-fields; correct the named fields there, then select the button again. Writing a profile document by hand repairs nothing: the offer stands down as soon as zotlit-profile.default.md exists, whatever the file holds.

• No item, or no annotation, to verify against. Connect a Zotero database that contains an item, then try again. or Add an annotation to a Zotero item, then try again. Connect a Zotero library that contains an item, then select the button again. The annotation notice appears only when an annotation file is among the files being converted.

• A converted document already exists. The converted profile document already exists. Rename or remove it, then try again. Rename or remove the file in the way, then select the button again. The notice says "profile document" even when the occupant is zotlit-citation.md or a partial.

• No legacy templates left to convert. No legacy template files need conversion. ZotLit found none of the files the conversion reads, so nothing is written and nothing changes. Keep using the built-in templates.

While the conversion is pending

Until you convert, ZotLit refuses to create, update, or switch a note through any profile other than the Default profile. The notice reads Convert the legacy literature note templates before you use an added profile.. Notes on the Default profile are unaffected. Every profile document action stays locked until the conversion has run: the Profiles page shows no Add and no Import, and the actions on the rows it keeps, such as Edit, Duplicate, Share, and Delete, are disabled.

Expected result

Your 2.1 files sit in Obsidian's configured trash, and the converted documents render the same output. A notice reads Literature note templates converted. The old files are in the system trash. Every profile works again.

See also