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 changedCopy anchor link

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 upgradeCopy anchor link

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 readyCopy anchor link

What the conversion doesCopy anchor link

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 setup banner shows the same list, headed 以下旧文件未能移入回收站，仍留在仓库中： Select 重试清理 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 旧版模板文件已转换。引用文本按 Liquid 转换，以下 Eta 文件保持原样，不再影响引用：…。.

What is refused, and what you seeCopy anchor link

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 编辑配置方案 after the conversion.

• A converted output that does not reproduce the old one. ZotLit 未更改旧版模板，因为转换后的 … 不一致。请从这些文件中移除每次运行都会变化的内容后重试，或将它们移出模板文件夹以使用内置模板：…。 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 无法转换这些文件：…。问题：…。请修正文件后重试，或将它们移出模板文件夹以使用内置模板。 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 模板 is off; turn the gate on under Settings > ZotLit > 高级 > 模板引擎 and try again.

• A frontmatter field written in JavaScript while the gate is off. 启用 JavaScript 模板，然后重试转换；受影响的托管 Frontmatter 字段：…。 Turn on JavaScript 模板 under Settings > ZotLit > 高级 > 模板引擎, then select the button again. See Enable JavaScript templates.

• No item, or no annotation, to verify against. 请连接一个含有条目的 Zotero 数据库，然后重试。 or 请为 Zotero 条目添加一条标注，然后重试。 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. 转换后的配置方案文档已存在。请重命名或移除该文档，然后重试。 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.

• A failure outside your templates. ZotLit 无法转换模板：…。请检查 Zotero 连接和模板文件夹，然后重试。 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. 没有需要转换的旧版模板文件。 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 fixCopy anchor link

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: 模板已转换。创建笔记前，请修正这些属性：…。前往 设置 → ZotLit → 文献笔记配置方案，然后选择“编辑配置方案”。 ZotLit refuses to create a note through that profile until the field works, and the refusal names the field. Select 编辑配置方案 under Settings > ZotLit > 文献笔记配置方案, correct the field, and save.

While the conversion is pendingCopy anchor link

Until you convert, ZotLit refuses to create, update, or switch a note through any profile other than the Default profile. The notice reads 请先转换旧版文献笔记模板，再使用其他配置方案。. 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 resultCopy anchor link

Your 2.1 files sit in Obsidian's configured trash, and the converted documents render the same output. A notice reads 文献笔记模板已转换。旧文件已移至系统回收站。 Every profile works again.

See alsoCopy anchor link