Eta template syntax

This page documents the Eta template language as configured in ZotLit. Eta templates require the JavaScript templates gate to be enabled. For the default Liquid engine, see Template syntax.

All template data is accessible through a single variable, zt. The shape of zt depends on the template type: see the Data reference for the full property list.

DelimitersCopy Anchor Link

<%= %> and <%~ %> are functionally identical in ZotLit. Both pass their result through the auto-filter. Use either for output; <%= %> is conventional.

<%= zt.title %>
<% if (zt.abstract) { %>
<%= zt.abstract %>
<% } %>

Use <%/* */%> for comments that do not appear in the rendered note:

<%/* Draft: revisit multi-author rendering */%>

Whitespace controlCopy Anchor Link

By default, ZotLit sets autoTrim to [false, false]: whitespace around tags is preserved exactly as written. Newlines after %> and indentation before <% appear in the rendered note.

Per-tag markers override this default on one side of the tag:

<% for (const annotation of zt.annotations) { -%>
- <%= annotation.text %>
<% } %>

The trailing -%> consumes the newline immediately after the opening tag, so each iteration begins on the - line.

Global autoTrim settingCopy Anchor Link

Two settings control default trim behavior when the JavaScript templates gate is on:

• Trim whitespace before tags: applies to the opening side of every tag.
• Trim whitespace after tags: applies to the closing side of every tag.

Each accepts three values: Keep (no trim), Strip one newline, or Strip all whitespace. Per-tag markers always override the global setting for that tag.

Auto-filter (output coercion)Copy Anchor Link

Every <%= %> and <%~ %> expression passes through a filter function before rendering. The filter coerces values to Markdown-safe text:

This means <%= zt.someFieldThatIsNull %> outputs nothing rather than the literal text "null". Creator objects and dates render through their toString() method: creators produce their full name, dates produce ISO strings.

The zt variableCopy Anchor Link

All template data lives under the zt variable. The variable name applies across all template types:

<%= zt.title %>
<%= zt.creators[0].family %>
<%= zt.citationKey %>

The editor autocomplete inserts = zt. when you select the interpolation hint inside <%= %> tags.

zt replaces v1's it variable. See Migrate v1 Eta templates for the full property mapping.

renderAnnotation(): annotation renderingCopy Anchor Link

Renders one annotation, available as zt inside the annotation template.

<%~ renderAnnotation(annotation) %>

The annotation argument is required. A missing or null value raises an error.

For an annotation value, the equivalent native Eta syntax is:

<%~ include("annotation", annotation) %>

In a Literature Note profile, the shortcut and native calls to annotation use the profile's Annotation Section. This required final section starts after the exact standalone line --- zotlit:annotation --- and continues to the end of the document. It uses the profile's language and can be empty.

Calls from shared partials use the calling profile's section, with isolated annotation data. Direct annotation insertion and Imported Notes use the same section for their applicable profile. Outside profile rendering, the shortcut keeps the existing named-template lookup.

include(): composing templatesCopy Anchor Link

include() renders another template inline. Pass the template name and an optional data argument:

<%~ include("annotation", annotation) %>
<%~ include("content", zt) %>

The data argument becomes the child template's zt variable, direct passthrough not merged with the parent's data. When omitted, the child inherits the parent's zt.

The name resolves to a registered template, not to a file path. During profile rendering, "annotation" selects the profile's Annotation Section.

Calling a partialCopy Anchor Link

A partial is called by its name, with the data it needs as the second argument:

<%~ include("authors", zt) %>

The argument becomes the partial's zt. Omit it and the partial inherits the caller's zt. Completion inside include(" lists every partial in the vault, and accepting a name writes the whole call, zt argument included. A call you have already given arguments keeps them, and only the name is replaced.

The content includeCopy Anchor Link

When include("content", zt) is called from the note template and a content template file in your vault backs it, ZotLit wraps the output with managed-region markers (%%zt-managed%% / %%/zt-managed%%). These markers never appear in a template document. They are injected at render time. The built-in content template renders without markers.

bq(): blockquote helperCopy Anchor Link

Wraps its content in a Markdown blockquote. Every line is prefixed with > . The content is trimmed. Consecutive blank lines inside the block collapse into a single bare >.

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

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

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

Rendered output:

> [!note] Page 42
>
> ![[excerpt.png]]The highlighted passage
>
> My thoughts on this

bq() must appear in a <% %> execute tag. It captures all output produced inside the callback, trims the result, prefixes each line with > (empty lines become bare >), collapses consecutive bare > lines into one, and writes the result to the output.

When the captured content is empty, bq() renders a lone >.

embed(): embed helperCopy Anchor Link

Turns a link helper into a Markdown embed by prefixing !. Returns "" when the link is null, undefined, or renders empty.

<%= embed(zt.imgLink) %>
<%= embed(zt.imgLink, "alt text") %>

Signature: embed(link, alias?, subpath?)

For image and ink annotations, embed(zt.imgLink) uses the prepared note image or returns an unavailable-image explanation and source link. It preserves that fallback text without adding !. Image preparation runs before the template, so the template executes once per render. Preview rendering creates no vault image files.

pandocCite(): Pandoc Citation sourceCopy Anchor Link

Formats a Citation Item array as Pandoc Citation source. Pass zt.citations directly to the helper.

<%= pandocCite(zt.citations) %>
<%= pandocCite(zt.citations, "prefer-author-in-text") %>

Signature: pandocCite(citations, form?)

The optional form is "normal" by default.

The helper handles all Citation Item properties used in Pandoc source:

Items with a null citation key are omitted. The helper preserves the order of the remaining items and adds braces around complex citation keys when Pandoc requires them.

Input that cannot be represented without changing its citation structure raises a render error.

texCite(): LaTeX citation commandCopy Anchor Link

Formats a Citation Item array as one LaTeX citation command. Pass zt.citations directly to the helper.

<%= texCite(zt.citations) %>
<%= texCite(zt.citations, "autocite") %>

Signature: texCite(citations, command?)

The optional command is "cite" by default. Write it without the backslash. A starred command such as "autocite*" is accepted.

Every retained item joins one key list. The command carries one prenote and one postnote, and both come from the first retained item:

Items with a null citation key are omitted, and the remaining items keep their order.

An affix reaches LaTeX as source, so a prefix of \emph{see} renders as emphasis. These inputs raise a render error instead:

• suppressAuthor set to true, which LaTeX has no general form for.
• A prefix, suffix, or locator on any item after the first, which has no slot.
• An empty citation key, or one that holds whitespace, a comma, or a TeX special character.
• A prefix, suffix, or locator whose braces do not balance, or which holds an unescaped %.

suffix(): filename collision guardCopy Anchor Link

For the filename template only. Appends a random string when the generated filename collides with an existing note. When the name is free, it renders nothing.

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

• First note named Smith2020 produces Smith2020.md.
• A second note that would also render Smith2020 produces Smith2020_a1b2c3.md.

SignatureCopy Anchor Link

suffix(length?, prepend?, append?)

The affixes appear only on collision. On a free name, the entire expression (affixes included) renders nothing.

<%= zt.title %><%= suffix(10) %>
<%= zt.title %><%= suffix(6, "(", ")") %>
<%= zt.citationKey %><%= suffix(4, "-") %>

The random string uses an alphanumeric alphabet. On collision, ZotLit retries up to 5 times with fresh random strings.

Link helpersCopy Anchor Link

Links on the zt context are functions, not precomputed strings. Call them to render. Each accepts optional overrides:

linkHelper(alias?, subpath?)

• alias: display text for the link. Omit to use the default (filename or note title).
• subpath: a #-fragment appended to the target, e.g. "#heading" or "#page=3".

<%= zt.attachments[0].fileLink() %>
<%= zt.attachments[0].fileLink("Open the PDF") %>
<%= zt.noteLink("See notes", "#Summary") %>

zt.noteLink() returns null when the literature note path is unresolvable (collision, recursive resolution, or template error). zt.imgLink is null for annotation types other than image and ink. An unavailable image uses the excerpt fallback.

The durable annotation linkCopy Anchor Link

zt.backlink on the annotation context is the durable link to the annotation. It is Zotero's own open link, and it names the attachment and the annotation by their Zotero keys:

zotero://open/library/items/<attachmentKey>?annotation=<annotationKey>&page=<pageLabel>

A group library has groups/<groupID> in place of library. page is the printed page label, and the link omits it when the annotation has none.

zt.backlink is a plain URL string, not a helper. Do not call it; wrap it in a Markdown link yourself, as the default annotation template does:

<%= zt.pageLabel ? `Page [${zt.pageLabel}](${zt.backlink})` : `[Zotero](${zt.backlink})` %>

While Settings > ZotLit > Reader > Open PDF file links in Obsidian is on, which is the default, clicking a durable annotation link opens the PDF in Obsidian, with the annotation selected. When this computer does not hold the PDF, Zotero opens the link instead. See Zotero open links for every case. A file link to a PDF in your Zotero library also opens in Obsidian, and an older zt.fileLink() link still opens on the annotation's page.

Template document namingCopy Anchor Link

A template document sits directly inside the folder set by Settings > ZotLit > Advanced > Template folder. The scan is flat, and the filename prefix alone says what a document is: zotlit-profile.<slug>.md for a profile, zotlit-citation.md for the citation text, and zotlit-partial.<name>.md for one partial. See Template document naming for the full rule and the reserved partial names.

An Eta document declares its language in a YAML manifest at the top of the file, before the source:

---
language: eta
---

<%= zt.title %>

language is the manifest's only legal key, and its values are liquid and eta. A document with no manifest is Liquid, so every Eta citation document and Eta partial needs this block. Switch a document between the two from the Template Workbench View's pane menu, with Change language; it rewrites the manifest key and leaves the source as written.

A profile document declares its language with the language key of its own manifest.

No asyncCopy Anchor Link

ZotLit renders templates synchronously. async/await is not available inside Eta templates.

See alsoCopy Anchor Link