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 模板文档 row, select its pencil button, tooltipped 编辑配置方案.
The Template Workbench View opens on the Default profile. Select the 属性 tab.
Add a new field
Select 添加属性. Each property has these controls:
- 属性名称 is the YAML property name written to frontmatter.
- 值格式 selects Zotero 字段 · Liquid, 固定文本, or 规则 · JSON-e.
- 值 is the field value or rule. Use
zt.paths such aszt.titleorzt.DOIfor Zotero data. - 笔记更新时 controls how ZotLit applies the value when it updates a note.
Choose a merge strategy
Use 替换现有值 to overwrite the field on every update, 添加到现有列表 to add new array items and keep the ones already in the note, or 保留现有值 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 属性 tab, select 添加属性 and enter these values:
| Input | Value |
|---|---|
| 属性名称 | tags |
| 值格式 | Zotero 字段 · Liquid |
| 值 | zt.tags | obsidian_tag |
| 笔记更新时 | 替换现有值 |
The 替换现有值 strategy keeps the note's Zotero tags in sync. Choose 添加到现有列表 when you want to keep manual Obsidian tags too.
Update the note
Run ZotLit: 更新文献笔记元数据 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 template 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 移除属性 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.
Drag the handle (拖动以调整顺序) at the start of a property row to move the property up or down. You can also select the handle and press Alt+Arrow Up or Alt+Arrow Down to move the row.
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 属性 tab marks a row it cannot use with 问题, and the 问题 area names what went wrong and offers 编辑属性 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: 更新文献笔记元数据This 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 template 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 模板 are off on
that device, and ZotLit reports the affected fields:
由于 JavaScript 模板已禁用，以下 Frontmatter 字段未生效：…。 See Enable
JavaScript templates.
See also
Install the ZotLit skills
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