How templates work

Templates are Markdown files with embedded expressions that control what your literature notes and citations look like. ZotLit keeps them in one folder in your vault as template documents, and reads the filename to decide what each one does.

Three kinds of template documentCopy Anchor Link

Every template document is one of three kinds. The filename prefix says which.

A profile document is the single authoring object for a literature note: its name, its properties, its body, and the format of one annotation all live in that one file. See Literature notes and the managed region for how ZotLit updates a note it has already written.

The citation text is the one source for every in-text citation: what you insert from the citation suggester or the command palette, the citation an annotation carries, and each citation inside an imported Zotero note. It receives zt.variant, the string main or alt, naming the gesture that asked for the citation, and the template decides what each one renders. alt comes from Shift+Enter, or from a trailing / in the suggester query; annotations and imported notes are always main. See What each gesture inserts.

Partials are how a piece of template text is shared. Several profiles, and the citation text, can render the same partial by name. See Customize a template for the steps.

How ZotLit finds themCopy Anchor Link

ZotLit scans the template folder for files whose name starts with zotlit-. The scan is flat: it reads the files directly inside the folder and does not descend into subfolders.

A file without the zotlit- prefix is ignored, so your own Obsidian templates can sit in the same folder.

A zotlit- file that is neither one of the three kinds nor a 2.1 template file renders nothing. It gets an Unrecognized ZotLit file row at Settings > ZotLit > Advanced > Template engine, naming the file and the three valid names. zotlit-citation.liquid.md is one such file: the citation text carries no language in its name.

Template folderCopy Anchor Link

Template documents live under the folder set at Settings > ZotLit > Advanced > Template folder, templates by default. Loading and file watching both use that folder. ZotLit recompiles a changed document immediately, so edits take effect without reloading the plugin.

The manifest and the languageCopy Anchor Link

A citation text or partial document is an optional YAML manifest, then the template source:

---
language: eta
---
<template source>

language is the only key the manifest accepts, and its only values are liquid and eta. Any other key is an error.

A document with no frontmatter is Liquid. A Liquid partial or citation text needs no manifest, and the file ZotLit creates for you when you first open the citation text carries none.

To change the language for a citation text or a partial, use the switch in the Template Workbench View. It rewrites the manifest key alone: your source is never translated between the two syntaxes.

A profile document always carries a manifest, because its manifest also holds the profile's name, folder, and citation style.

Two template languagesCopy Anchor Link

ZotLit supports two template languages: Liquid and Eta.

Liquid is the default. It is always active and requires no opt-in. Liquid templates can only combine data into text: they cannot read files, make network requests, or run system commands. That makes them safe to share, sync, and install from community sources.

Eta is a JavaScript-based engine. Eta templates can run arbitrary JavaScript with the same access as ZotLit itself. Because of the wider security surface, Eta is disabled by default and requires a per-device opt-in called the JavaScript templates gate. See JavaScript templates for the full explanation.

An Eta document is inert while the gate is off. It is not compiled, and it does not fall back to the built-in default. ZotLit names the file it skipped and says why.

Built-in defaultsCopy Anchor Link

The citation text works with no file in your vault: ZotLit renders a built-in Liquid default instead. Its settings row reads Using the built-in default. until a document exists. Opening the row creates the document from that built-in text, and resetting it moves your document to Obsidian's configured trash so the built-in text takes over again.

Literature notes work the same way through the built-in Default profile, which you customize into a document of your own.

Converting 2.1 template filesCopy Anchor Link

Template files from ZotLit 2.1 still load and still render, so you do not have to convert them to keep working. That covers zotlit-note.liquid.md, zotlit-content.liquid.md, zotlit-annotation.liquid.md, zotlit-filename.liquid.md, the two citation files, and any other zotlit-<name>.(liquid|eta).md that served as a partial.

ZotLit offers the conversion in the setup banner above the Library View, as Convert your literature note templates, and repeats it as a reminder row at the top of settings with a Review conversion action. One pass folds the note, content, filename, and annotation files into one profile document, folds the two citation files into one citation text, and gives every remaining file its own partial document.

Before it writes anything, ZotLit renders both citation variants and the note, update, filename, and annotation output, and compares them byte for byte against what your old files produced. A mismatch converts nothing. The old files then go to Obsidian's configured trash, so you can recover them.

See Migrate v1 Eta templates for the steps and the field mappings a v1 template also needs.

When two 2.1 files share a nameCopy Anchor Link

A 2.1 name could carry both a .liquid.md and an .eta.md file. While both exist, the Liquid file wins and the Eta file is ignored, whether or not JavaScript templates are enabled. The conversion trashes both.

See alsoCopy Anchor Link