Migrate v1 Eta templates

Rename template filesCopy Anchor Link

v2 reads templates from a zotlit- prefix, replacing zt-, and the template formerly called annots is now content. Rename your files to these names first. ZotLit loads and renders them under these names, and the one-pass conversion below folds them into v2's template documents.

Your two v1 citation files, zt-cite*.eta.md, take the same zt- to zotlit- rename. Both of them fold into one citation text document, zotlit-citation.md, as an if/else on zt.variant.

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 ztCopy Anchor Link

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 fieldsCopy Anchor Link

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 accessCopy Anchor Link

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 accessCopy Anchor Link

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 fieldsCopy Anchor Link

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 accessCopy Anchor Link

v1 inlined child-note content as Markdown on it.notes. v2 provides link-only entries. A child note becomes a separate file only when you import it:

The default template no longer lists child notes. To list them as links, add a loop like this to your template:

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

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

Rewrite the annotation template with bq()Copy Anchor Link

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 templateCopy Anchor Link

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 annotations alone.

Update the citation sourceCopy Anchor Link

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).
• Both of your v1 citation files render from one v2 document. The conversion below writes them as the two branches of an if/else on zt.variant, which is "main" or "alt". See Citation templates.

Update attachment accessCopy Anchor Link

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 accessCopy Anchor Link

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 (the first populated role: primary creator, editor, director, then contributor) and zt.authorsShort (formatted short string, e.g. "Smith et al.").

Update the filename templateCopy Anchor Link

The filename template is a template file (zotlit-filename.eta.md), not a setting string. The one-pass conversion later folds it into the filename key of your profile document's manifest. 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 fieldsCopy Anchor Link

If you customized zt-field.eta.md, delete it and rebuild its fields as managed frontmatter entries in your profile document. Open the document from the Templates and properties row at Settings > ZotLit with Edit profile, then select the Properties tab.

For each field, select Add a property and fill in:

• Property name: the YAML property name.
• Value format: Zotero field · Liquid for a Zotero field, Fixed text for fixed text, or Rule · JSON-e for a JSON-e rule.
• Value: the value. A Zotero field uses a zt. path, such as zt.title.
• When the note is updated: Replace the existing value, Add to the existing list, or Keep the existing value.

YAML escaping is handled automatically.

The Properties tab writes each property as one entry in the frontmatter list of the profile document manifest. An entry carries a key and one value member, and the member name declares the language: expr holds a Liquid value, which is what Zotero field · Liquid writes; value holds fixed text or a JSON-e rule, which is what Fixed text and Rule · JSON-e write; and js holds a JavaScript value, which you write in Source.

ZotLit manages reserved frontmatter keys that you cannot target from a user field, such as zotero-key, zotlit-profile, zotero-note-key, and zotero-lastmod. The default citekey entry is an ordinary managed frontmatter field. See Frontmatter reference for details.

Overwrite v1 notes to add the managed regionCopy Anchor Link

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. Your renamed zotlit-content template becomes the managed region, so ZotLit inserts the managed-region markers.

After overwriting, the note responds to ZotLit: Update literature note for incremental updates. 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.