Configure frontmatter properties
Add custom YAML frontmatter fields to literature notes using template expressions and merge strategies.
Available sinceZotLit 2.0.0
You can map Zotero data into YAML frontmatter properties that appear at the top of every literature note. ZotLit ships four default fields: title, related, collections, and citekey.
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.
Add Zotero tags to note frontmatter
Create a managed tags field with the obsidian_tag filter. The filter reads
Zotero tag objects from zt.tags and returns an array of Obsidian tag values.
Add the tags field
In Settings > ZotLit > Templates > Frontmatter, add a field with these values:
| Input | Value |
|---|---|
| Key | tags |
| Language | Liquid |
| Expression | zt.tags | obsidian_tag |
| Merge strategy | Replace |
The Replace strategy keeps the note's Zotero tags in sync. Choose
Append arrays when you want to keep manual Obsidian tags too.
Update the note
Run ZotLit: Update literature note metadata on an existing literature note. ZotLit evaluates the field and writes the result to its frontmatter.
For example, Zotero tags named Methodology and Open Access become:
tags:
- Methodology
- Open_AccessThe filter normalizes spaces and other characters according to Obsidian's tag
rules. Frontmatter tag values do not need a leading #. See the obsidian_tag
filter reference for all
normalization rules.
For agent-assisted setup, install the ZotLit skill and
ask the agent to add a managed tags field with the expression
zt.tags | obsidian_tag. The Template Workbench
lets the agent configure the field and test the rendered result.
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.
Reorder fields
The order of fields in the Frontmatter list determines the order of frontmatter keys when ZotLit creates a new literature note. On a new note, the system identity field zotero-key follows the user-configured fields.
To change the order, drag a field by the handle on its row in Settings > ZotLit > Templates > Frontmatter.
Existing notes
Reordering the list does not change property order in notes that already exist. When ZotLit updates an existing note, a key already present in that note's YAML keeps its current position.
To reorder properties within a single note, use Obsidian's properties panel: drag the property type icon to the left of a property name to move that row. Obsidian writes the new key order back into the note's YAML. The note must have two or more properties for this to work.
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,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.
The default citekey field uses zt.citationKey, Liquid, and Replace. It writes null when the Zotero item has no citation key. You can edit or remove this field because it is not reserved.
Agent-based configuration
An agent with the ZotLit skill can configure managed frontmatter field templates through the Template Workbench CLI. See Template Workbench for details.
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.
See also
Install the ZotLit skill
Let an agent configure and test managed frontmatter fields.
How templates work
Template types, languages, and the data model.
Explore template data
Browse available zt.* fields and copy paths.
Enable JavaScript templates
Turn on the gate to use Eta expressions in frontmatter fields.
Template Workbench
Configure managed frontmatter field templates through the Obsidian CLI.