How templates work

Templates are Markdown files with embedded expressions that control what your literature notes, citations, and filenames look like. Each template type handles one piece of the output, and you can customize any of them by ejecting the built-in default into your vault.

Template types

ZotLit uses six template types. Each type receives data from Zotero and renders one piece of output.

The content template is the one whose output is wrapped in managed-region markers. When you run an update, only the content between those markers is replaced. See Literature notes and the managed region for details.

Two template languages

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.

Filename matching

Template files follow a strict naming pattern:

zotlit-<name>.<language>.md

The <name> slot accepts any combination of alphanumeric characters and hyphens. The <language> portion is either liquid or eta. The pattern is case-sensitive.

The six canonical names in the table above (filename, note, annotation, content, cite, cite2) each bind to a template type. A file with a canonical name overrides that type's built-in default. Files with non-canonical names are also compiled and can be referenced from other templates via include().

Examples: zotlit-note.liquid.md, zotlit-annotation.eta.md.

Liquid-wins shadowing

Both a .liquid.md and a .eta.md file can exist for the same template name at the same time. When both are present, the Liquid file always takes precedence, regardless of whether JavaScript templates are enabled. The shadowed Eta file is reported with a warning in Settings > Templates:

The Eta template at {path} is ignored because a Liquid template with the same name takes precedence.

Built-in defaults and ejecting

Every template type ships with a built-in Liquid default. When no vault file exists for a template name, ZotLit uses the embedded default.

To customize a template, you eject it: the built-in default is copied into your vault's template folder as a .liquid.md file and opened for editing. Each template's row in Settings > Templates shows a Create editable template file action when that template still uses the default.

Once ejected, the file is yours. ZotLit watches the template folder and recompiles any changed file immediately. Edits take effect without reloading the plugin.

Restoring the default

Deleting an ejected template file returns that template to the built-in default. No plugin reload is needed. The watcher picks up the deletion and reverts immediately. See Customize a template for the steps.

Template folder

All template files live under the folder configured in Settings > Templates > Template folder. Ejecting, loading, and file watching all use that folder.

Switching languages

Each template can use either Liquid or Eta. Switching to Eta trashes the Liquid file (recoverable) and reveals an existing .eta.md or creates one from the built-in Eta default. Switching to Liquid trashes the .eta.md and the template reverts to an existing Liquid file or the built-in default.

The switch never converts content between the two syntaxes: it replaces the file. Switching to Eta requires the JavaScript Templates gate to be on. See Customize a template and Enable JavaScript templates for the procedures.

See also