Configure frontmatter properties
Add custom YAML frontmatter fields to literature notes using template expressions and merge strategies.
You can map Zotero data into YAML frontmatter properties that appear at the top of every literature note. ZotLit ships three default fields (title, related, collections) and you can add your own.
Add a frontmatter field
Open the Frontmatter sub-page
In Obsidian, open Settings > ZotLit > Templates > Frontmatter. This sub-page lists all configured user fields.
Add a new field
Click the add button. A modal opens with four inputs:
- Key: the YAML property name written to frontmatter.
- Language: Liquid or JavaScript. The JavaScript option appears only when the JavaScript Templates gate is enabled on that device.
- Expression: the template expression whose output becomes the field value. Use
zt.paths (e.g.zt.title,zt.DOI). Browse available paths with the Template Data Explorer. - Merge strategy: controls how the value is applied on note update.
Choose a merge strategy
Three strategies are available:
| Strategy | Behavior on update |
|---|---|
| Replace | Overwrites the field with the new value every time. |
| Append arrays | Adds new array items without removing existing ones. |
| Keep existing | Writes the field only if it does not already exist in frontmatter. |
Save
Click Save. If validation passes, the field is added to the list.
Edit or remove a field
Click a field's row to reopen the edit modal and change its settings. To remove a field, use the delete control on its row in the Frontmatter list.
Validation rules
The modal rejects invalid configurations:
- Empty key: "Enter a key."
- Reserved key: "'
{key}' is managed by ZotLit and can't be used." Reserved keys arezotero-key,citekey,zotero-note-key, andzotero-lastmod. - Duplicate key: "'
{key}' is already mapped." - Empty expression: "Enter an expression."
- Syntax error: surfaced on save when the expression fails to compile.
Apply updated fields to existing notes
After changing frontmatter configuration, run:
ZotLit: Update literature note metadataThis re-evaluates all field expressions and writes the results to the active note's frontmatter according to each field's merge strategy.
JavaScript fields and the gate
A frontmatter field with Language set to JavaScript is inert when the JavaScript Templates gate is off on that device. The settings page shows: "This field is inactive because JavaScript templates are disabled on this device." See Enable JavaScript templates.