Migrate v1 Eta templates

Rename template files

v2 templates use a zotlit- prefix (replacing zt-) and the template formerly called annots is now content.

Delete these files if present (they have no v2 equivalent):

• zt-field.eta.md: replaced by the settings-based frontmatter system.
• zt-colored.eta.md: color styling is now handled automatically during note import.

Replace it with zt

The template data variable changed from it to zt. A search-and-replace of it. to zt. within template tags covers most cases:

it.title       →  zt.title
it.creators    →  zt.creators
it.backlink    →  zt.backlink
it.pageLabel   →  zt.pageLabel

The exceptions below (comment, tags, collections, date, notes) have changed semantics. Handle them in the following steps rather than with a blanket replace.

Update renamed and reshaped fields

These fields changed name or type:

Direct Zotero fields that are plain strings (title, DOI, url, volume, issue, pages, publisher, etc.) carry over unchanged after the it → zt rename.

Update tag access

v1 exposed tags as formatted strings. v2 exposes them as objects with name and type properties. Tags coerce to their name in string contexts, so join still works:

<%/* Tags coerce to their name */%>
<%= zt.tags.join(", ") %>

<%/* Explicit property access */%>
<%= zt.tags.map(t => t.name).join(", ") %>

<%/* Filter to manual tags only */%>
<%= zt.tags.filter(t => t.type === "manual").join(", ") %>

Update collection access

v2 reshapes collection objects. Key differences:

<%/* Collections coerce to their name in string contexts */%>
<%= zt.collections.join(", ") %>

<%/* Render each collection's full hierarchy */%>
<%= zt.collections.map(c => c.path.join(" > ")).join("; ") %>

Update date fields

If your v1 template used it.date as a year string, replace with zt.date?.year:

<%/* v1 */%>
year: "<%= it.date %>"

<%/* v2 */%>
year: "<%= zt.date?.year %>"

Update child note access

v1 inlined child-note content as Markdown on it.notes. v2 writes each child note to a separate file and provides link-only entries:

The default content template renders child notes as a bulleted list of links:

<% if (zt.notes.length) { %>
## Notes

<% for (const note of zt.notes) { -%>
- <%~ note.noteLink() %>
<% } %>
<% } %>

Rewrite the annotation template with bq()

v1 relied on external blockquote handling. v2 uses the bq() helper inside the annotation template:

<% bq(() => { %>
[!note] Page <%= zt.pageLabel %>

<%= embed(zt.imgLink) %><%= zt.text %>
<% if (zt.comment) { %>

<%= zt.comment %>
<% } %>
<% }) %>

bq() wraps all content in a Markdown blockquote (> per line), trims the result, and collapses consecutive empty blockquote lines. It must appear in a <% %> execute tag.

Update the content template

The template is renamed from annots to content. It now receives the full context object instead of a raw annotation array:

<%/* v1: received a raw array as `it` */%>
<% for (const annotation of it) { %>

<%/* v2: receives full context, access annotations via zt.annotations */%>
<% for (const annotation of zt.annotations) { %>

Update the include call in your note template:

<%/* v1 */%>
<%~ include("annots", it.annotations) %>

<%/* v2 */%>
<%~ include("content", zt) %>

The content template now has access to all zt.* properties (attachments, tags, notes, etc.), not only annotations.

Update citation templates

v1 passed it as a raw array. v2 wraps items in an object:

<%/* v1 */%>
[<%= it.filter(lit => !!lit.citekey).map(lit => `@${lit.citekey}`).join("; ") %>]

<%/* v2 */%>
[<%= zt.citations.filter(c => c.item.citationKey).map(c =>
  `${c.suppressAuthor ? "-" : ""}@${c.item.citationKey}`
).join("; ") %>]

Key changes:

• it (array) becomes zt.citations (array inside an object). zt.items exposes the same items without citation metadata.
• lit.citekey becomes c.item.citationKey (or c.item.citekey).

Update attachment access

v1 selected one attachment and exposed it as it.fileLink (a string). v2 provides all attachments as an array, and fileLink is a link helper you call:

<%= zt.attachments.map(a => a.fileLink()).filter(Boolean).join(" ") %>

Each attachment object has: key, filename, contentType, linkMode, filePath, fileLink.

Update creator access

v2 uses a flat array with explicit properties. Creators coerce to their full name in string contexts:

<%/* All authors (coerces to fullName) */%>
<%= zt.authors.join(", ") %>

<%/* Explicit property access */%>
<%= zt.authors.map(c => c.fullName).join(", ") %>

<%/* Filter by role */%>
<%= zt.creators.filter(c => c.role === "editor").join(", ") %>

Creator properties: family, given, literal (institutional names), role, fullName.

Convenience properties on the item context: zt.authors (primary creator type) and zt.authorsShort (formatted short string, e.g. "Smith et al.").

Update the filename template

The filename template is a template file (zotlit-filename.eta.md), not a setting string. The v2 default adds suffix() for collision avoidance:

<%= zt.citationKey ?? zt.DOI ?? zt.title ?? zt.key %><%= suffix() %>

• it.citekey becomes zt.citationKey (canonical name; zt.citekey also works).
• The .md extension is no longer included. ZotLit appends it automatically.
• suffix() appends a random string only when the name collides with an existing note.

Migrate frontmatter fields

If you customized zt-field.eta.md, delete it and recreate the fields in Settings > ZotLit > Templates > Frontmatter:

For each field, configure:

• Key: the YAML property name.
• Expression: a JavaScript or Liquid expression evaluated against zt.
• Language: select JavaScript to use JS expressions (requires the JavaScript Templates gate), or Liquid for Liquid expressions.
• Merge strategy: Replace, Append arrays, or Keep existing.

YAML escaping is handled automatically.

ZotLit manages reserved frontmatter keys that you cannot target from a user field. For literature notes: zotero-key and citekey. For imported notes: zotero-note-key and zotero-lastmod. See Frontmatter reference for details.

Overwrite v1 notes to add the managed region

v1 notes lack the %%zt-managed%% / %%/zt-managed%% markers that v2 uses to isolate generated content. Incremental update cannot target their body. Running ZotLit: Update literature note on a v1 note refreshes frontmatter only.

To add the managed region, run the overwrite command on each note you want refreshed:

A confirmation modal appears. Click Overwrite to proceed. ZotLit regenerates the entire note body from the current templates, inserting the managed-region markers.

After overwriting, the note responds to ZotLit: Update literature note for incremental updates going forward. You do not need to overwrite every note at once. Leave notes untouched until you are ready.

See Refresh v1 notes for the full procedure.