Migrate from 2.1 templates
Keep your 2.1 template files working, then convert them to profile documents when you are ready.
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.
| 2.1 file | 2.2 home |
|---|---|
zotlit-note.<lang>.md | The note source of zotlit-profile.default.md |
zotlit-content.<lang>.md | The managed block inside that note source |
zotlit-filename.<lang>.md | The filename key of the profile document manifest |
zotlit-annotation.<lang>.md | The Annotation Section, after the --- zotlit:annotation --- header |
zotlit-cite.<lang>.md and zotlit-cite2.<lang>.md | The two branches of the one zotlit-citation.md citation text |
Any other zotlit-<name>.<lang>.md | Its own zotlit-partial.<name>.md partial |
| The frontmatter field list in settings | The frontmatter list in the manifest, which holds managed frontmatter entries |
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
Open the conversion offer
The offer sits in the setup banner above the Library View, titled Convert your literature note templates. Show the banner with ZotLit: Open welcome view, or use the reminder row at the top of Settings > ZotLit.
Select Convert templates
Select Convert templates and wait for the conversion to finish. Dismissing the banner without converting leaves everything as it was, and the reminder row stays at the top of Settings > ZotLit with a Review conversion action.
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 setup banner 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 banner 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
Your vault and your settings stay as they were after every refusal. Each one reports a notice, and the banner keeps the same sentence next to the button until you try again. If you do not want to fix a 2.1 file, move it out of the template folder: ZotLit then uses the built-in template for that part, and you can copy your changes into the profile with Edit profile after the conversion.
-
A converted output that does not reproduce the old one. ZotLit kept the legacy templates unchanged because the converted … did not match. Remove anything that changes on each run from these files and try again, or move them out of the template folder to use the built-in templates: …. 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, oralternate 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 could not convert these files: …. Problem: …. Fix the files and try again, or move them out of the template folder to use the built-in templates. 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 and names the problem, with a line number when ZotLit has one. A template that fails to render, or a line such as
--- zotlit:notes ---that ZotLit keeps for its own use, also reports this notice. Edit the files 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.
-
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.mdor a partial. -
A failure outside your templates. ZotLit could not convert the templates: …. Check the Zotero connection and the template folder, then try again. ZotLit could not read Zotero or could not write to the template folder. Any document this attempt already wrote is removed. Fix the cause the notice names, then select the button again.
-
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.
Properties that need a fix
A frontmatter field that fails against the item ZotLit picked does not stop the conversion. ZotLit keeps the field exactly as you wrote it, and a notice names it: Templates converted. Before you create notes, fix these properties: …. Go to Settings → ZotLit → Literature note profiles and select Edit profile. ZotLit refuses to create a note through that profile until the field works, and the refusal names the field. Select Edit profile under Settings > ZotLit > Literature note profiles, correct the field, and save.
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
Last updated on