Settings

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

Open settings from Settings > ZotLit. The sections below follow the order of the settings tab: the main page first, then each sub-page.

Settings moved in ZotLit 2.2.0. Where settings moved maps each old location to its new one.

Main pageCopy Anchor Link

The main page opens when you select ZotLit in Obsidian's settings. It holds the default Profile's settings. New literature notes use this Profile when no other Profile is selected.

The top of the page links to the release notes, the documentation, the community, and the bug report form. Reminders appear in the same place.

Three of these rows are bindings: the two note folders and the citation and references style. The Imported notes page holds the other two bindings. ZotLit stores all five in note.default-profile.bindings in data.json, and every other Profile inherits a binding it does not set itself. The fourth row opens the Profile's document. See Settings > ZotLit > Literature note profiles.

Template conversion reminderCopy Anchor Link

A vault whose 2.1 template files still wait for conversion keeps one reminder at the top of the page. The row is Convert your literature note templates and its one button is Review conversion, which opens the Library View with the conversion in its setup banner. Its description reads:

Legacy templates stay active until you convert them. Review the conversion when you are ready.

See Migrate from 2.1 templates.

Literature note folderCopy Anchor Link

The folder part of a new literature note's path. ZotLit creates the note in this folder, under the name that the Profile's note name template gives, and adds .md. A slash (/) in that name makes a subfolder in this folder. For example, the folder literatures and the name 2024/Smith2020 give literatures/2024/Smith2020.md.

A Profile can set its own folder, and a note stays in the folder of the Profile it was created with. A Profile switch or a Profile deletion can move the note. The move keeps the subfolders the note has under its Profile's folder.

Imported note folderCopy Anchor Link

Where ZotLit saves notes imported from Zotero. A Profile can set its own folder. ZotLit creates the folder when it is absent, and gives each filename a short random suffix so every imported note keeps its own file.

See Import Zotero notes for the import workflow.

Citation and references styleCopy Anchor Link

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. In a native Pandoc run, Default uses the Pandoc default style, Chicago author-date.

An unavailable style remains selected. In-text citations stay native, and the References Sidebar shows its minimal list. The row then reads This style isn’t installed in Zotero. Install it in Zotero or select another style..

The first formatting attempt shows The selected citation and references style isn’t installed in Zotero. once per plugin lifecycle. Its Open settings action opens ZotLit settings.

Built-in export with an unavailable style stops and shows Zotero cannot supply …. Install it in Zotero, or choose another style for this export. A native Pandoc run of a note that uses the unavailable style stops with style-missing. Neither export uses another style.

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. A native Pandoc run cites each note with the style the note uses in Obsidian, unless the note sets csl or citation-style, or you pass --csl.

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 under the banner This note's citation and references style is unavailable, and the copy action stays 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.

Template documentCopy Anchor Link

The document that renders a literature note: its filename, its properties, and its body.

The main page exposes it through one row, Templates and properties, whose description reads Edit the default profile in the template workbench.. Edit profile opens the Profile in the Template Workbench View and creates the document from the built-in Literature Note Template while it does not exist yet.

Once the document exists, the row also offers Restore built-in, which moves it to Obsidian's configured trash and returns the Profile to the built-in template.

PropertiesCopy Anchor Link

The properties ZotLit writes into every literature note it creates and updates.

The properties live in the Profile's template document, edited through the same Templates and properties row on the main page. While the Profile uses the built-in template, ZotLit writes its built-in field list. Creating the document starts from the fields the Profile already writes, so no field is lost.

See Configure frontmatter properties for what each field does.

Literature note profilesCopy Anchor Link

Open this page from Settings > ZotLit > Literature note profiles. A Profile's template document defines its note folder, citation style, and appearance. It can also carry a Profile Match: conditions that select the Profile automatically for new literature notes. See Profiles for how ZotLit selects one.

The first row is Default, the default Profile: Uses the settings on the main ZotLit page. Other profiles inherit from it. Its buttons are Edit profile and More actions, whose menu holds Share….

The Other profiles list holds every other Profile. Its header carries two buttons. Add profile opens a dialog that reads Start from a copy of the current Default template. The literature note folder is optional: leave it empty to use the Default folder. Existing notes keep their folders. Its fields are Name and Literature note folder, and the new document then opens in the Template Workbench View. A valid name is enough to create the Profile. The folder is optional: while it is empty, its placeholder shows the folder the Profile inherits, for example Same as Default — literatures. Import profile… reads a Profile in from your clipboard or a file. Until you add one, the list reads Add one to use a different folder, citation style, or look for some notes..

Each added Profile has one row showing its label and a short Profile Match status:

A row carries one button for the Profile and one menu for everything else:

A new Profile starts with the default Profile's template. Its own document can set a folder, citation style, appearance, or Profile Match.

Each Profile is edited in its own document. Deleting a Profile that notes still use asks where those notes go first. The dialog can also move the notes into the folders of the Profile they go to. Its checkbox names those folders, for example Move files to books/. The move keeps the subfolders a note has under the deleted Profile's folder. A note outside that folder moves by its file name alone.

PartialsCopy Anchor Link

The Partials list at Settings > ZotLit > Literature note profiles > Partials holds every partial in the vault. A partial is a piece of template text that any template renders by name, so several Profiles can share it. The list sits below the Profile list, and it covers the whole vault rather than one Profile.

Until you add one, the list reads Add one to share a piece of template text between profiles. Its header carries one action, Add partial, which asks for a name and creates the file.

Each partial has one row with its name and its vault path:

The delete confirmation reads Delete partial? with the body … will be moved to trash. Every template that calls this partial will report a problem. It rewrites no caller, so every template that calls the deleted partial reports a missing partial afterwards.

Renaming a partial is an ordinary Obsidian file rename. ZotLit has no rename action and rewrites no call, so each caller reports a missing partial until you change the name in the call yourself.

A partial file whose name belongs to another ZotLit template registers nothing and gets its own row instead:

See template document naming for the reserved names and the filename rule.

Profile MatchCopy Anchor Link

A Profile Match is the set of conditions that select a Profile automatically for new literature notes. Each condition tests a Zotero item with the same conditions as the filter of an items Query View, such as its title, creators, year, item type, Collections, Library, or Tags. The Match lives in the Profile's template document. The default Profile is the fallback: it has no Profile Match.

Nothing on this page edits a Match. A Profile row reports the status word from the table above, and the row's own controls act on the Profile rather than its conditions. Change the conditions in the Profile's document, on the Match tab of the Template Workbench View. See Use different templates for that procedure, and Profile Match for the condition language, its operators, and the Collection path rules.

ZotLit skips a Profile Match that it cannot evaluate. The cause is a mistake in the expression: invalid syntax, an unknown function or method, or an incorrect argument. The Profile row then shows Needs attention, and the Match tab shows the same error as a Query View, on the row that has the mistake. A condition that names a Library or item type that does not exist is not a mistake: it matches no item. Other Profiles continue to take part in automatic selection. A template document that ZotLit cannot load appears in Excluded documents and takes no part in selection.

Selection for new notesCopy Anchor Link

When exactly one Profile Match fits an item, ZotLit uses that Profile and creates the literature note directly. The creation notice reports the Profile, the match reason, and the note path.

When two or more Profiles match, the Profile picker opens with the matching candidates identified. Select a Profile for the current operation. Exclusions in the Match conditions can prevent future overlaps.

When none matches, the picker preselects Default. ZotLit uses it directly when no other Profile exists.

Selection follows this order:

1. Your manual choice for the current operation.
2. A Profile supplied by a command or a link from ZotLit Companion, the Zotero add-on.
3. The one matching Profile.
4. The default Profile.

Once a creation preview is ready, its Profile and destination stay fixed for that operation. Changes to Match conditions apply to the next operation.

In a batch, ZotLit selects a Profile separately for each item. A shared fallback choice covers unmatched or overlapping items; items with one matching Profile keep that selection. Use one profile for all new notes… applies your choice to every new note in the batch.

Existing notes keep their recorded Profile when Match conditions change. The changes apply to new notes.

Share and importCopy Anchor Link

The Share… dialog and import consent dialog control whether a Profile carries its Match conditions:

The import consent dialog shows the incoming Match conditions as their Filter Expression. When the incoming Profile has no Profile Match, the dialog shows Not auto-selected and hides Import match conditions.

Library references, Collection paths, and Tag names stay as written during sharing and import. Review the imported conditions against your own Libraries, Collections, and Tags on the Match tab of the Template Workbench View.

Imported notesCopy Anchor Link

Open this page from Settings > ZotLit > Imported notes. It holds how notes imported from Zotero render. Their folder is on the main page.

The first and third rows are bindings of the default Profile; ZotLit stores them with the main page's bindings in note.default-profile.bindings.

Highlight mappings is a sub-page with one row per Zotero highlight color. Each row takes

HTML mark

, a circle emoji, or

Custom

with an emoji of your own. The mappings apply to all Profiles.

See Import Zotero notes for how the mappings render.

CitationsCopy Anchor Link

Open this page from Settings > ZotLit > Citations.

Citation suggestionsCopy Anchor Link

Citation sourcesCopy Anchor Link

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.

Annotation citations: Count Zotero annotation links with no link text, such as [](zotero://…), as citations of the annotation's item in the references sidebar and ZotLit's in-text features. This setting does not change export.

All three settings can be off. ZotLit's internal Citation Index remains active, and Reset citation index remains available under Settings > ZotLit > Advanced.

Graph viewCopy Anchor Link

Show citations in graph view: Connect each note to works it cites in the graph view: to the Literature Note, or to a node labeled with the citation key when no Literature Note exists. Turning it off returns every open graph to its native state, and the Citation Graph commands report that it is off instead of opening.

The setting is vault-wide. The Graph view core plugin supplies the graph views themselves: while that plugin is disabled, no graph shows citations and the row reports it. See Explore citations in the graph view.

In-text citationsCopy Anchor Link

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.

HoverCopy Anchor Link

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.

A durable annotation link shows its annotation under both Citation popover and Page preview. Under Page preview, it waits for Ctrl (Windows) or Command (macOS) exactly when the Page preview plugin's ZotLit citation key row asks for it, as a citation does.

Require modifier keyCopy Anchor Link

Show the popover only while holding Ctrl (Windows) or Command (macOS). The sub-page appears only while Hover action is Citation popover, and lists toggles for editing modes and the graph view.

Each toggle applies to its editing mode or the graph view. ZotLit checks the modifier when the pointer arrives.

FormattingCopy Anchor Link

Citation and references style is on the main page. See Citation and references style.

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 with 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 under the banner This note's document language is invalid, the copy action stays unavailable, and built-in export stops before the dialog opens.

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 reads Not installed. References stay a plain list until you install it.. This supported state does not show a lifecycle notice.

Citation textCopy Anchor Link

One row, after the Formatting group. Citation text: The text inserted when you pick items in the citation suggester. It covers both citation gestures; the template itself decides what the main and the alternate gesture render.

A second line under the description names the document. While the vault holds no citation document, that line reads Using the built-in default.; once the document exists, it is the document's vault path. The document is zotlit-citation.md in the folder set by Settings > ZotLit > Advanced > Template folder.

The row carries two icon-only buttons, whose names below are their tooltips:

The reset confirmation reads Reset citation text? with the body … will be moved to trash. New citations use the built-in citation text. Reset trashes the file rather than rewriting its contents, so you can recover it from the trash. A notice follows: Citation text reset.

The row adds a warning line in two cases:

In both cases the citation text is inert. Inserting a citation shows the same message as a notice, and ZotLit does not fall back to the built-in text. See Citation templates for the data a citation template receives, and Citation text for the built-in default.

Native Pandoc workflowCopy Anchor Link

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

Pandoc citation tutorial: Opens Build a Pandoc citation workflow at its stable URL.

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

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

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

ZoteroCopy Anchor Link

Open this page from Settings > ZotLit > Zotero. It holds the connection to Zotero, the libraries ZotLit reads, and how ZotLit stays current with Zotero.

Zotero locationCopy Anchor Link

Open this sub-page from Settings > ZotLit > Zotero > Zotero location. These rows set where and how ZotLit reads Zotero. Change them when ZotLit cannot find your Zotero library or shows outdated data.

Read mode options:

LibrariesCopy Anchor Link

Library scopeCopy Anchor Link

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 libraryCopy Anchor Link

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 unavailableCopy Anchor Link

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

Your saved scope is untouched. See Fix Zotero changes that do not appear for the connection itself.

Recovery from an invalid scopeCopy Anchor Link

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 Library scope is invalid as a notice 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.

Sync with ZoteroCopy Anchor Link

Receive updates from Zotero lets ZotLit answer ZotLit Companion's notifications. The notifications arrive through the local server, which is off by default. Turn on Run a local server in the Local server group for updates to arrive. Open local server settings opens that group. See Set up live updates for the Companion connection.

EditingCopy Anchor Link

Zotero editingCopy Anchor Link

Zotero editing shows whether ZotLit can change annotations in Zotero. Reading annotations needs no permission. Editing needs four things:

• Zotero 10 or later.
• Zotero running on the same computer.
• In Zotero, Allow other applications on this computer to communicate with Zotero turned on, under Settings → Advanced.
• Your permission. Select Allow editing, and when Zotero asks, choose Always Allow. Allow alone leaves editing off.

The row shows only the actions that apply at the moment:

ZotLit saves the permission for this vault on this device only, in Obsidian's Keychain. Another computer that shares the vault asks for its own permission. See Edit PDF annotations in Obsidian.

AttachmentsCopy Anchor Link

Open this page from Settings > ZotLit > Attachments.

Generated excerpt images require Import attachments. When it is off, ZotLit creates no new excerpt files for notes. It keeps a verified existing image when possible; otherwise it writes an unavailable-image explanation and source link. The annotation view and its device cache work independently of this setting.

Approved foldersCopy Anchor Link

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 copied content such as 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.

The sub-page's first row is Import policy: Approval applies to future imports; re-import previously imported notes to copy attachments that were skipped.

ReaderCopy Anchor Link

Open this page from Settings > ZotLit > Reader. It controls what ZotLit does when it opens a PDF in Obsidian's reader.

Reveal the annotation view opens the annotation view in the sidebar each time ZotLit opens a PDF. Turn it off to keep the sidebar as it is.

Open PDF file links in Obsidian opens a file link in a note in Obsidian's PDF viewer when the link points to a PDF in your Zotero library. Every other file link opens in your system app. A link you right-click and send to your system app also opens there. Turn it off to open all file links in your system app.

Open annotation links in ZotLit reader opens a durable annotation link in Obsidian's PDF viewer with the annotation selected. When off, the link opens in Zotero. Hovering the link still shows the annotation. Open PDF file links in Obsidian must also be on.

See Open an item's PDF in Obsidian.

AdvancedCopy Anchor Link

Open this page from Settings > ZotLit > Advanced.

Update notices opens the Library View after ZotLit updates, with a banner above it that names the new version and links to the release notes.

Template engineCopy Anchor Link

Template folder is where editable template files, including Profile documents, are created and loaded from.

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

Options for Trim whitespace before tags and Trim whitespace after tags: Keep, Strip one newline, Strip all whitespace.

Unrecognized ZotLit filesCopy Anchor Link

A zotlit- file in the template folder that is neither a template document nor a 2.1 template file gets one diagnostic row in this group:

A file without the zotlit- prefix is ignored and gets no row. See template document naming.

Local ServerCopy Anchor Link

The server binds to the configured hostname, which defaults to this computer's loopback address. It tries the configured port, then up to 9 higher ports, stopping at 65535. Port in use reports the port actually used. ZotLit Companion's notification URL must use that port.

Turning off Run a local server stops Live Update connections. Receive updates from Zotero keeps its value and is in the Sync with Zotero group on Settings > ZotLit > Zotero.

LoggingCopy Anchor Link

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.

RecoveryCopy Anchor Link

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.

Excerpt image cacheCopy Anchor Link

Clear excerpt image cache removes ZotLit's cached excerpt images for this vault on this device. Select Clear cache in the confirmation to clear it. Saved note images and Zotero's image cache remain unchanged.

The cache survives restarts and has a 256 MiB limit. ZotLit removes the least recently used entries when it needs space. Cleared images are generated again when requested. See Cache and freshness for the PDF file checks and their limits.

Where settings movedCopy Anchor Link

ZotLit 2.2.0 reorganized the settings tab around the literature note. Every row keeps its name, so Obsidian's own settings search still finds a setting by the name you know. Settings new in 2.2.0, such as Highlight mappings, are not listed here; they appear only in their own section above.

The legacy template rows for the literature note, the managed region, the annotation, and the note filename are no longer in settings. A literature note's body, filename, and properties come from its Profile's template document.

See alsoCopy Anchor Link