Settings
Every ZotLit setting: key, label, default value, and location in the settings tab.
This page documents every setting exposed by ZotLit, grouped by the settings tab where it appears. Each entry lists the UI label, internal key, control type, and default value.
Open settings from Settings > Community plugins > ZotLit.
Hub (top-level)
The hub page shows when you first open ZotLit settings.
| Label | Key | Control | Default |
|---|---|---|---|
| Default library | zotero.citation-library | Dropdown (lists your Zotero libraries) | My Library |
| Literature note folder | note.literature-folder | Folder picker | literatures |
Citations
Open this page from Settings → ZotLit → Citations.
Citation suggestions
| Label | Key | Control | Default |
|---|---|---|---|
| Citation suggester | citation.editor-suggester | Toggle | On |
@ trigger | citation.at-trigger | Toggle | Off |
| Show citation key in suggestions | citation.show-citekey-in-suggester | Toggle | Off |
@ trigger is visible only when Citation suggester is on.
Citation key links
| Label | Key | Control | Default |
|---|---|---|---|
| Citation key links | citation.key-links | Toggle | Off |
| Citation key property | citation.key-links-frontmatter-key | Text | citekey |
Citation key property is visible only when Citation key links is on. Earlier settings migrations keep Citation key links on. New installs use the off default.
Citation key links opens bracketed citation keys in Live Preview and Source mode. The setting description links to How citation key links work and notes that the feature uses an internal Obsidian editor integration.
Citation key property names the Literature Note frontmatter property used for citation key lookup. The value must be non-empty and cannot start or end with spaces.
Zotero database
Device Overrides
Zotero profile and Data directory override are stored per device and never sync through the vault. Setting either value on one computer does not affect other computers that share the same vault. When unset, ZotLit auto-detects the default Zotero location. See Use ZotLit on multiple devices for details.
| Label | Key | Control | Default | Storage |
|---|---|---|---|---|
| Zotero profile | (device-local) | Profile picker | Auto-detect | Per device |
| Zotero database | (read-only) | Displays resolved zotero.sqlite path | — | — |
| Read mode | zotero.read-mode | Dropdown | Auto | Synced |
| Watch for changes | zotero.auto-refresh | Toggle | On | Synced |
Read mode options:
| Option | Behavior |
|---|---|
| Auto | Picks the best available mode for your platform. See How ZotLit connects to Zotero for details. |
| Reflink clone | Fast, lightweight snapshot. Default on macOS. |
| Full copy | Byte-for-byte copy of the database file. Works on any filesystem but slower and uses more disk space. Auto does not select this mode. |
| Immutable source | Reads the database file directly. Default on Windows and Linux. Recent edits in Zotero may not appear immediately. |
Advanced
| Label | Key | Control | Default | Storage |
|---|---|---|---|---|
| Data directory override | (device-local) | Folder picker | Auto-detect | Per device |
| Source ID | (read-only) | Displays the 8-character hex identifier for the connected Zotero install | — | — |
Templates
| Label | Key | Control | Default |
|---|---|---|---|
| Template folder | template.folder | Folder picker | templates |
JavaScript templates
JavaScript (Eta) templates are gated behind a per-device toggle. Enabling shows a confirmation modal.
| Label | Key | Control | Default |
|---|---|---|---|
| JavaScript templates | (per-device gate) | Turn on / Turn off button | Off |
| Auto-pair Eta tags | template.auto-pair-eta | Toggle | Off |
| Trim whitespace before tags | template.auto-trim-leading | Dropdown | Keep |
| Trim whitespace after tags | template.auto-trim-trailing | Dropdown | Keep |
The three settings below the gate are visible only when JavaScript templates are enabled.
Trim whitespace options: Keep, Strip one newline, Strip all whitespace.
Template files
This group lists one row per template type, in order: Note filename, Literature note, Annotation, Managed region, Citation, Alternate citation.
Each row provides:
- Create editable template file: ejects the built-in default to a file you can edit.
- Open template: opens the ejected file in the editor.
- Reset to default: deletes the ejected file and reverts to the built-in (destructive; requires confirmation).
- Delete template file: removes the ejected file (destructive; requires confirmation).
- Language: dropdown to switch between Liquid and JavaScript (Eta).
A Create all editable template files button at the top of the group ejects every template at once.
Template files > Frontmatter
A sub-page managing the note.frontmatter-fields setting as an editable list. Each field row has:
| Column | Description |
|---|---|
| Key | The YAML frontmatter key name |
| Expression | Template expression that produces the value |
| Language | Liquid or JavaScript (Eta) |
| Merge strategy | How the field is updated on re-render: Replace, Append arrays, or Keep existing |
Actions: Add field, Reset to default (reverts the full list).
Note import
| Label | Key | Control | Default |
|---|---|---|---|
| Imported note folder | note.import-folder | Folder picker | zotero_notes |
| Render annotations from template | note.import-annotations-as-template | Toggle | Off |
Attachments
| Label | Key | Control | Default |
|---|---|---|---|
| Import attachments | attachment.import | Toggle | On |
| Attachment folder | attachment.folder-path | Folder picker | (Obsidian default) |
| Approved folders | (device-local) | Sub-page listing the folders attachments may be imported from | Empty |
Attachment folder is visible only when Import attachments is on.
Approved folders
The folders ZotLit may copy attachments from, beyond Zotero's own storage folder, its annotation cache, and the linked-attachment base folder you set in Zotero. This setting protects imports of Zotero linked files. A linked file stays in an external folder instead of being copied into Zotero storage. See Zotero's guide to linked files.
This approval applies to imported content such as annotation images and images embedded in Child Notes. The ordinary attachment links in a Literature Note point to the original files and do not copy them.
When imported content is outside all approved locations, ZotLit uses a file:// URI. A notice reports how many files it skipped, lists the unapproved source folders, and links to ZotLit settings.
Actions: Add folder (opens a folder picker), and delete on each row. Approval applies to future imports. Re-import previously imported notes to copy attachments that were skipped.
Device Overrides
Approved folders are stored per device and never sync through the vault. Approving a folder on one computer grants nothing on another computer, and nothing in another vault.
Live updates
| Label | Key | Control | Default |
|---|---|---|---|
| Receive updates from Zotero | server.enabled | Toggle | Off |
| Port | server.port | Number (1024 -- 65535) | 9091 |
Port and Hostname are visible only when Receive updates from Zotero is on.
Advanced
| Label | Key | Control | Default |
|---|---|---|---|
| Hostname | server.hostname | Text | 127.0.0.1 |
Diagnostics
| Label | Key | Control | Default |
|---|---|---|---|
| Log level | log.level | Dropdown | info |
| Write logs to file | log.to-file | Toggle | Off |
Log level options: Off, trace, debug, info, warning, error, fatal.
When Write logs to file is on, logs append to zotlit.log.jsonl inside the plugin folder. Two additional action rows appear:
- Open log file: opens the JSONL log in the system editor.
- Save log archive: exports the log file for sharing.
Both actions are disabled while Write logs to file is off.
Reset language packs removes the downloaded language packs stored on this device and forgets whether ZotLit already offered them. The pack loaded at startup stays in place until you restart Obsidian, after which ZotLit offers to install it again. Use it when translated text looks wrong or outdated.