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 four default fields: title, related, collections, and citekey.
Properties belong to a profile
Each profile stores its property rules in its profile document's manifest. The Template Workbench View changes those rules and saves the document automatically. See Profile document for the manifest. See Frontmatter for the field mechanics, the merge strategies, and the reserved keys.
Add a frontmatter field
Open the Template Workbench View
In Obsidian, open Settings > ZotLit. On the Templates and properties row, select its pencil button, tooltipped Edit profile.
The Template Workbench View opens on the Default profile. Select the Properties tab.
Add a new field
Select Add a property. Each property has these controls:
- Property name is the YAML property name written to frontmatter.
- Value format selects Zotero field · Liquid, Fixed text, or Rule · JSON-e.
- Value is the field value or rule. Use
zt.paths such aszt.titleorzt.DOIfor Zotero data. - When the note is updated controls how ZotLit applies the value when it updates a note.
Choose a merge strategy
Use Replace the existing value to overwrite the field on every update, Add to the existing list to add new array items and keep the ones already in the note, or Keep the existing value to write the field only when it is blank. See Merge strategies for how each one behaves.
Check the result
The Template Workbench View saves the property automatically. Check the preview to see the value for the selected paper.
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 the Properties tab, select Add a property and enter these values:
| Input | Value |
|---|---|
| Property name | tags |
| Value format | Zotero field · Liquid |
| Value | zt.tags | obsidian_tag |
| When the note is updated | Replace the existing value |
The Replace the existing value strategy keeps the note's Zotero tags in sync. Choose Add to the existing list 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
CLI lets the agent configure
the field and test the rendered result.
Edit or remove a field
Select a property row to edit it. Use Remove property to remove it.
Reorder fields
The order of the properties in the Template Workbench View determines the order of frontmatter keys when ZotLit creates a new literature note.
Use Move up or Move down to move a property.
Existing notes
Reordering the fields 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 Properties tab marks a row it cannot use with Problem, and the Problems area names what went wrong and offers Edit property to open the row.
See Validation for the rules ZotLit applies, and Edit a profile as Markdown for the area that reports them.
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 shipped fields are ordinary entries, so you can edit or remove citekey here. See Default fields for what the Default profile declares.
Agent-based configuration
An agent with the ZotLit skill can configure managed frontmatter field templates through the Template Workbench CLI.
JavaScript fields and the gate
A property declares its value with one member. expr holds one Liquid
expression, value holds one JSON-e rule (fixed text is a rule that is a
plain string), and js holds one JavaScript expression. A js property is
inert while JavaScript templates are off on
that device, and ZotLit reports the affected fields:
These frontmatter fields are inactive because JavaScript templates are disabled: …. 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 run js properties in frontmatter.
Template Workbench CLI
Configure managed frontmatter field templates through the Obsidian CLI.
Last updated on