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 > 文献笔记配置方案.

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 转换文献笔记模板 and its one button is 查看转换, which opens the Library View with the conversion in its setup banner. Its description reads:

旧版模板会一直生效，直到您完成转换。准备好后即可查看转换。

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 此样式未安装在 Zotero 中。请在 Zotero 中安装该样式，或选择其他样式。.

The first formatting attempt shows 所选的引用与参考文献样式未安装在 Zotero 中。 once per plugin lifecycle. Its 打开设置 action opens ZotLit settings.

Built-in export with an unavailable style stops and shows Zotero 无法提供 …。请在 Zotero 中安装该样式，或为本次导出选择其他样式。 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 参考文献 Sidebar, the 引用弹出框, 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 参考文献 Sidebar shows its minimal list under the banner 此笔记的引用与参考文献样式不可用, 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, 模板文档, whose description reads 在模板工作台中编辑默认配置方案。. 编辑配置方案 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 恢复内置, 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 模板文档 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 > 文献笔记配置方案. 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 默认, the default Profile: 设置其他配置方案继承的值。 Its buttons are 编辑配置方案 and 更多操作, whose menu holds 分享….

The 其他配置方案 list holds every other Profile. Its header carries two buttons. 添加配置方案 opens a dialog that reads 以当前默认配置方案模板的副本开始。文献笔记文件夹为可选项：留空则使用默认配置方案的文件夹。现有笔记将保留其文件夹。 Its fields are 名称 and 文献笔记文件夹, 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 与默认配置方案相同 — literatures. 导入配置方案… reads a Profile in from your clipboard or a file. Until you add one, the list reads 添加一个配置方案，即可为部分笔记使用不同的文件夹、引文样式或外观。.

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 将文件移至 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 片段 list at Settings > ZotLit > 文献笔记配置方案 > 片段 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 添加一个片段，即可在多个配置之间共享同一段模板文本。 Its header carries one action, 添加片段, 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 删除片段？ with the body … 将被移至回收站。调用该片段的模板都会报告问题。 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 匹配 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 需要检查, 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 已排除的文档 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 默认. 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. 所有新笔记使用同一配置方案… 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 分享… 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 不自动选择 and hides 导入匹配条件.

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 匹配 tab of the Template Workbench View.

Imported notesCopy anchor link

Open this page from Settings > ZotLit > 导入笔记. 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.

高亮映射 is a sub-page with one row per Zotero highlight color. Each row takes

HTML 标记

, a circle emoji, or

自定义

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 > 引文.

Citation suggestionsCopy anchor link

Citation sourcesCopy anchor link

Pandoc 引用: 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.

Wiki 链接引用: 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.

批注引用: 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 重置引用索引 remains available under Settings > ZotLit > 高级.

Graph viewCopy anchor link

在关系图谱中显示引用: 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 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.

将批注链接显示为引用: Show annotation links with no link text, such as [](zotero://…), as the formatted citation of the annotation's item, with the annotation's page as the locator. [](zotero://…?annotation=…&page=12) shows as [@key, p. 12] would. Selecting the citation still opens the annotation. When off, these links stay links. Source mode always shows Markdown.

将引用作为链接打开: 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. 悬停行为 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

悬停行为: What hovering a citation or literature note link shows. Page preview follows the Page preview plugin settings.

One hover shows one result. 引用弹出框 shows the bibliography entry of every cited item. 页面预览 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. 关闭 adds no ZotLit hover result.

A durable annotation link shows its annotation on every hover, whatever 悬停行为 is set to. Below the annotation, the popover shows the bibliography entry of the annotation's item, with the same actions as a citation popover. An annotation on a standalone PDF has no item, so its popover shows the annotation alone.

Require modifier keyCopy anchor link

Show the popover only while holding Ctrl (Windows) or Command (macOS). The sub-page appears only while 悬停行为 is 引用弹出框, 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

参考文献样式 is on the main page. See Citation and references style.

引用语言: 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 请输入语言代码，例如 en-US、de 或 zh-CN。.

The locale applies to in-text citations, the 参考文献 Sidebar, the 引用弹出框, 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 参考文献 Sidebar, the 引用弹出框, 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 参考文献 Sidebar shows its minimal list under the banner 此笔记的文档语言无效, the copy action stays unavailable, and built-in export stops before the dialog opens.

Both note properties are set from the ZotLit: 设置引文呈现方式 command, which is also in the note's More options menu. See Commands.

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

Before installation, its status reads 尚未安装。安装之前，参考文献以纯列表显示。. This supported state does not show a lifecycle notice.

Citation textCopy anchor link

One row, after the 参考文献 group. 引文文本: 在引文建议器中选择条目时插入的文本。 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 使用内置默认值。; once the document exists, it is the document's vault path. The document is zotlit-citation.md in the folder set by Settings > ZotLit > 高级 > 模板文件夹.

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

The reset confirmation reads 重置引文文本？ with the body … 将被移至回收站。新的引文将使用内置引文文本。 Reset trashes the file rather than rewriting its contents, so you can recover it from the trash. A notice follows: 已重置引文文本。

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 引文教程: Opens Build a Pandoc citation workflow at its stable URL.

Pandoc 集成文件对: Save the version-matched filter and defaults file to one folder. Keep both files together.

Pandoc CLI 指南: ZotLit reference for the native Pandoc workflow.

保存集成文件 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 位置. These rows set where and how ZotLit reads Zotero. Change them when ZotLit cannot find your Zotero library or shows outdated data.

读取模式 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.

所有文库 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.

选定文库 stays exactly as you set it. A group library you join later stays out of scope until you add it.

添加文库 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 选定文库 starts at 我的文库. Switching to 所有文库 discards the list you had.

ZotLit stores each selection as a stable reference: 我的文库 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 在当前 Zotero 数据库中不可用。 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 打开 Zotero 数据库以编辑文库范围。.

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 文库范围无效 as a notice once, marks the setting with a standing warning, and searches 我的文库 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

接收来自 Zotero 的更新 lets ZotLit answer ZotLit Companion's notifications. The notifications arrive through the local server, which is off by default. Turn on 运行本地服务器 in the Local server group for updates to arrive. 打开本地服务器设置 opens that group. See Set up live updates for the Companion connection.

EditingCopy anchor link

Zotero editingCopy anchor link

Zotero 编辑 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 允许编辑, 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.

SearchCopy anchor link

Chinese word searchCopy anchor link

中文分词器 installs a managed binary that splits Chinese titles into words. Until you install it, search splits Chinese titles with built-in rules, which miss some words. With it, the Library View, citation suggester, and quick switcher find more papers whose title holds your search term in the middle. The installation applies to every vault on this device.

The row installs the binary in one click and shows its status: downloading, installed with its version, or a checksum mismatch.

AttachmentsCopy anchor link

Open this page from Settings > ZotLit > 附件.

Generated excerpt images require 导入附件. 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: 添加文件夹 (opens a folder picker), and delete on each row.

The sub-page's first row is 导入策略: 批准仅适用于之后的导入；要复制之前跳过的附件，请重新导入已导入的笔记。

ReaderCopy anchor link

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

显示标注视图 opens the annotation view in the sidebar each time ZotLit opens a PDF. Turn it off to keep the sidebar as it is.

在 Obsidian 中打开 PDF 文件链接 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.

在 ZotLit 阅读器中打开标注链接 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. 在 Obsidian 中打开 PDF 文件链接 must also be on.

See Open an item's PDF in Obsidian.

AdvancedCopy anchor link

Open this page from Settings > ZotLit > 高级.

更新通知 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

模板文件夹 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 移除标签前的空白 and 移除标签后的空白: 保持, 去掉一个换行符, 去掉所有空格.

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. 正在使用的端口 reports the port actually used. ZotLit Companion's notification URL must use that port.

Turning off 运行本地服务器 stops Live Update connections. 接收来自 Zotero 的更新 keeps its value and is in the Sync with Zotero group on Settings > ZotLit > Zotero.

LoggingCopy anchor link

日志级别 options: 关闭, trace, debug, info, warning, error, fatal.

When 将日志写入文件 is on, logs append to zotlit.log.jsonl inside the plugin folder. Two additional action rows appear:

• 打开日志文件: opens the JSONL log in the system editor.
• 保存日志存档: exports the log file for sharing.

Both actions are disabled while 将日志写入文件 is off.

RecoveryCopy anchor link

重置引用索引 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.

重置语言包 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

清除摘录图片缓存 removes ZotLit's cached excerpt images for this vault on this device. Select 清除缓存 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 高亮映射, 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