Settings

This reference lists every ZotLit setting, its default, dependencies, and storage scope.

Open settings from Settings > Community plugins > ZotLit.

Hub (top-level)

The hub page shows when you first open ZotLit settings.

Library scope

The libraries ZotLit uses for item search, citation key resolution, and library-wide commands. Everything that already names one item, note, or library keeps that exact target: a menu entry or link from Zotero runs against the library it came from, and a literature note stays tied to its own item.

All libraries follows your Zotero database. A group library you join later is in scope at once, read-only groups included, and a group you leave drops out.

Selected libraries stays exactly as you set it. A group library you join later stays out of scope until you add it.

Add library offers the libraries you have not selected yet, and each row's delete action removes one. The last remaining row has no delete action, so the list is never empty.

Switching to Selected libraries starts at My Library. Switching to All libraries discards the list you had.

ZotLit stores each selection as a stable reference: My Library as itself, a group library by its Zotero group ID. Group names and Zotero's internal library numbers are never stored, so a renamed group keeps its place in the list and shows its current name.

An unavailable library

A selected group can be missing from the connected Zotero database, because you left the group or because you connected a different Zotero data directory. It keeps its place in the list and shows as Group {ID} with the note "Unavailable in this Zotero database." Rejoin the group to restore its name, or delete the row to drop it.

Search, citation key resolution, and library-wide commands run over the libraries that are available. A library-wide command states how many selected libraries it had to skip.

While the database is unavailable

ZotLit lists your libraries from the connected Zotero database. While that database is unreadable, the library scope controls are disabled and show "Open the Zotero database to edit the library scope."

Your saved scope is untouched. See Fix stale data from Zotero for the connection itself.

Recovery from an invalid scope

ZotLit can fail to read a saved scope, after an edited data.json or a vault synced from a newer ZotLit. It keeps the broken value on disk rather than overwriting it, and an unrelated settings change leaves that value in place.

ZotLit shows the notice "Library scope is invalid" once, marks the setting with a standing warning, and searches My Library alone until you repair the setting. The first change you make here writes over the broken value and clears both warnings.

Citations

Open this page from Settings > ZotLit > Citations.

Citation suggestions

Citation sources

Pandoc citations: Include Pandoc citations such as @doe2024 in the references sidebar and ZotLit’s in-text features. This setting does not change citation insertion or export.

Wikilink citations: Include unaliased links to literature notes in the references sidebar and ZotLit’s in-text features. Heading links, block links, and invalid citation fragments stay as links. This setting does not change export.

Both settings can be off. ZotLit's internal Citation Index remains active, and Reset citation index remains available under Maintenance.

In-text citations

Show formatted citations: Show citations in Live Preview and reading view with the selected citation and references style. Source mode always shows Markdown. Citations stay unchanged when ZotLit cannot format them.

Open citations as links: Open literature notes when you select a Pandoc citation or a literature note wikilink shown as a citation. When off, selecting a citation places the cursor in the citation text so you can edit it.

The navigation setting also controls the four open-under-cursor commands. Hover action owns hover on its own. While this setting is off, Ctrl-click (Windows and Linux) or Cmd-click (macOS) still opens the Literature Note.

Hover

Hover action: What hovering a citation or literature note link shows. Page preview follows the Page preview plugin settings.

One hover shows one result. Citation popover shows the bibliography entry of every cited item. Page preview shows the Literature Note of a single-item citation under the built-in Page preview plugin's own settings, and shows nothing for a multi-item citation. Off adds no ZotLit hover result.

Require modifier key

Show the popover only while holding Ctrl (Windows) or Command (macOS). The sub-page appears only while Hover action is Citation popover, and lists one toggle per editing mode, like the built-in Page preview plugin lists one toggle per hover source.

Each toggle gates the popover in its own editing mode, and the modifier is read when the pointer arrives.

Formatting

Citation and references style: CSL style used to format in-text citations and the references sidebar. Install and manage styles in Zotero.

The dropdown stores the CSL style ID. Default uses ZotLit's embedded style. ZotLit uses the embedded style only while Default is selected.

An unavailable style remains selected. In-text citations stay native, and the References Sidebar shows its minimal list. The row shows this warning:

This style isn’t installed in Zotero. Install it in Zotero or select another style.

The first formatting attempt shows this notice once per plugin lifecycle: "The selected citation and references style isn’t installed in Zotero." Its Open settings action opens the Citations page.

A note can select its own style with the zotlit-csl property. The property takes the CSL style ID of a style installed in Zotero. Every other note keeps the vault selection.

That note uses its own style for in-text citations, the References Sidebar, the Citation Popover, and the copied bibliography. The built-in export dialog opens on the same style. The dialog holds a style you pick there for that run alone, and never writes it to the note.

A note whose zotlit-csl names an unavailable style stops instead of using the vault selection. Its citations stay native. The References Sidebar shows its minimal list with this banner, and the copy action stays unavailable.

This note's citation and references style is unavailable

Built-in export of that note opens on the same unavailable style and stops with a notice, unless you pick an available style in the dialog.

An empty zotlit-csl property stops the note the same way, and its built-in export stops before the dialog opens. Remove the property to use the vault selection again.

Citation locale: Sets the language for citation terms, dates, names, and sorting. Leave empty to use the language the selected style declares.

The field takes a language tag such as en-US, de, or zh-CN. ZotLit rejects any other form and shows this message: "Enter a language code such as en-US, de, or zh-CN."

The locale applies to in-text citations, the References Sidebar, the Citation Popover, the copied bibliography, and built-in export. Built-in export applies it to citation processing only: a note that declares Pandoc lang keeps that language, and a note that declares none stays without one.

A note can set its own locale with the standard Pandoc lang property. The property takes the same language tags this field takes. It overrides this setting for that note across in-text citations, the References Sidebar, the Citation Popover, the copied bibliography, and built-in export. Built-in export also passes it to Pandoc as the exported document's own language.

A note whose lang is not a language tag stops instead of using this setting. Its citations stay native. The References Sidebar shows its minimal list with this banner, the copy action stays unavailable, and built-in export stops before the dialog opens.

This note's document language is invalid

Both note properties are set from the ZotLit: Set citation presentation command, which is also in the note's More options menu. See Commands.

Pandoc engine: Formats in-text citations, references, and exports. Installation applies to every vault on this device.

Before installation, its status is: "Not installed. References stay a plain list until you install it." This supported state does not show a lifecycle notice.

Native Pandoc workflow

These rows support conversion with a user-installed Pandoc CLI. They are separate from ZotLit's built-in export command.

Pandoc CLI guide: ZotLit reference for the native Pandoc workflow.

Pandoc integration pair: Save the version-matched filter and defaults file to one folder. Keep both files together.

Save integration files writes the pair to the folder you select. See Export a note with citations for ZotLit's built-in workflow.

Zotero database

Read mode options:

Advanced

Templates

JavaScript templates

JavaScript (Eta) templates are gated behind a per-device toggle. Enabling shows a confirmation modal.

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:

Actions: Add field, Reset to default (reverts the full list).

Note import

Attachments

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.

Live updates

Advanced

Maintenance

Update notices shows a notice linking to the release notes after ZotLit updates.

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 citation index clears the stored citation key scans and reads your notes again. ZotLit keeps a scan per note so that a restart only re-reads the notes that changed, and the scans are rebuilt from your vault, so nothing in your vault changes. Use it when the references sidebar disagrees with what a note cites. The rebuild runs in the background after you confirm.

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.

See also