v2.2.0-beta.0

ZotLit 2.2 gives a literature note template one document of its own, adds a workbench to edit it inside Obsidian, and draws your citations in the graph view.

HighlightsCopy anchor link

Citations in the graph viewCopy anchor link

Your citations now appear in Obsidian's graph. A note gains an edge to every work it cites, so literature notes stop floating unconnected and two notes that cite the same paper meet at its node. Where no literature note exists yet, the work appears as a dimmed Cited Work Node.

This is on as soon as you update. Every ordinary graph starts drawing citation edges and Cited Work Nodes, so your graph is busier than it was. 在关系图谱中显示引用 under Settings > ZotLit > 引文 turns it off again.

Six rows in the graph's own controls decide what each graph draws, built into the native Filters and Display sections and saved per graph like the native rows:

• Under Filters: Pandoc 引用 and Wiki 链接引用, both on, and 仅显示引用相关节点, off.
• Under Display: 作者和标题标签, 为引用连线着色, and 引用弹出框, all off.

Wiki 链接引用 appears only while the vault-wide wikilink citation setting is on. Restore default settings in the graph returns all six to their defaults along with the native options.

Literature notes keep the node colors Obsidian gives them. A Cited Work Node takes a dimmed color of its own, and citation edges take theirs only while 为引用连线着色 is on. Your own color groups still win, and one press of 添加文献笔记分组 in the Groups section colors every literature note without a search query. All three colors have theme hooks; see Theme hooks.

作者和标题标签 writes the authors and the year above each work, with the short title dimmer underneath. Zooming in brings the titles out, and hovering shows one at any zoom. The graph's search box still matches your files, not the labels on screen.

Hover needs the per-graph 引用弹出框 row, which starts off. With it on, hovering a literature note or a cited work follows your Hover Action setting, and Settings > ZotLit > 引文 > 需要按住修饰键 adds a 关系图谱 row so the graph alone requires a held modifier key. A work with no literature note, and a note nothing cites, now show the formatted entry in the popover instead of Obsidian's page preview.

Select a Cited Work Node to create its literature note from the profile and open it; the key that matches one item becomes the note node, with the same edges. Right-click one for 创建文献笔记, 在 Zotero 中打开, and 复制文献引用标识（citation key）. A key that matches several items keeps its dimmed node.

ZotLit: 打开引用关系图谱 and ZotLit: 打开局部引用关系图谱 open the graph arranged for reading as a research map: citation edges in, every node except your literature notes, cited works, and the notes that cite them hidden, arrows on, labels and the popover on, and the literature notes group added. A global graph keeps one set of options for the whole vault, so the first command saves that arrangement as your graph settings. The local command needs an open note.

If a command opens nothing, ZotLit says why: the Graph core plugin is off, the citations switch is off, or the citation graph is unavailable. Explore citations in the graph view is the full guide.

Literature note profilesCopy anchor link

2.1 built a literature note from separate files: a note file, a managed-region file, a filename file, an annotation file, and a frontmatter field list that lived in settings. 2.2 puts the whole note into one Markdown document per profile. Each zotlit-profile.<slug>.md in your template folder holds the note name, the note folder, the properties, the note body, and the annotation format together.

Two companions complete the set. zotlit-citation.md holds the text of every inserted citation, once for the whole vault, and each zotlit-partial.<name>.md holds template text that several profiles share. Profile document gives the format of all three.

Settings > ZotLit > 文献笔记配置方案 is the new home of all of this. The 默认 row is your default layout; 添加配置方案 creates another profile, and 导入配置方案… reads one in from a file or the clipboard. A profile's own row offers 编辑配置方案 and a 更多操作 menu with 复制配置方案, 分享…, and 删除配置方案. A profile's match is edited on the workbench's 匹配 tab.

Below the profiles sits the 片段 list, with 添加片段 and 打开片段. A document ZotLit cannot read, or one whose ID collides with another profile's, is listed under 已排除的文档 instead of being used.

引文文本 under Settings > ZotLit > 引文 opens the citation document, and its 重置为默认值 button returns it to the built-in text once you have changed it.

A profile can also select itself. A Profile Match tests an item's library, item type, tags, or collections, and every new note that fits uses that profile. A profile without a Match stays manual. See Profile Match, and Use a different template for different notes for the steps from an empty profile to a matched one.

Every note records the profile that made it, so a later update uses the same template. ZotLit: 切换文献笔记配置方案 moves a note, and the imported notes that follow it, onto another profile.

Profiles explains how ZotLit picks one and how a note keeps it, How templates work covers the three kinds of document, and converting 2.1 template files the upgrade.

The Template WorkbenchCopy anchor link

Your templates have a view of their own now, with the fields beside the editor and the resulting note on the other side. ZotLit: Switch to template workbench view opens the document in your active note, and ZotLit: 打开模板工作台 opens all three panes together, in a window of their own when the editor would otherwise share one. From a literature note, ZotLit: Customize this note's template opens the profile that made it with that paper already selected.

The layout has three columns. The 模板字段 pane lists the Zotero data a template can read, the middle column edits the document, and the 笔记预览 pane shows the note that comes out. The panes are linked through Obsidian's own linked tabs, so choosing a paper or an annotation in one follows in the others.

The preview refreshes as you type. Its pane menu switches between 预览为新笔记, 预览为更新后的笔记, and 仅预览更新的部分, with 显示 Markdown to read the raw output. When you arrive from a literature note, the top bar names that note and offers 更新此笔记 to apply the change there at once.

Repeated text becomes a partial in one step. Select it, then choose 提取为片段…. 新建片段… starts one from scratch, the 片段 menu lists every partial in the vault, and 以 Markdown 打开 opens the same document in Obsidian's own editor.

Template Workbench View describes every way in, Customize a template walks through the profile, the citation text, and partials, and Edit a profile as Markdown is the route for anyone who would rather type the document.

Inside the Template Workbench ViewCopy anchor link

The editor is tabbed by part of the note: 笔记, 属性, 标注, 名称和文件夹, 匹配, and 配置方案. 源码 shows the whole document as source when you want it that way. Every edit saves as you go.

The editor knows the document's language. Liquid templates get their tags, variables, and filters highlighted, with the YAML manifest and the Markdown markers styled apart from the body. Eta templates pair tags as you type and gain the same suggestions and hover; the JavaScript 模板 gate governs rendering, not editing. Typing a field or a partial name offers what is available and what it holds.

When something fails, 问题 sits under the editor with what went wrong, which part of the document it came from, and the actions to reach it, including 复制错误报告 when you want to ask for help. Collect debug logs says what that report carries.

Properties covers the properties tab, and Template Workbench View the tabs, the languages, and the panes. The workbench view is part of the desktop app.

Breaking ChangesCopy anchor link

Four changes alter what you already have. Read them before you upgrade.

2.1 template files give way to documentsCopy anchor link

Nothing converts on its own. Your zotlit-note.liquid.md, zotlit-content.liquid.md, zotlit-filename.liquid.md, zotlit-annotation.liquid.md, the two citation files, and any file that served as a partial keep loading and rendering until you convert them. The Welcome view offers 转换文献笔记模板 once after the update, and settings repeat it with 查看转换. One press folds the note, managed-region, filename, and annotation files into zotlit-profile.default.md, the two citation files into zotlit-citation.md, and every remaining file into its own partial. ZotLit verifies byte-identical output before it writes anything, then moves the old files to Obsidian's configured trash. The pass needs one item from your Zotero library to verify against, and an annotation as well if you customized the annotation file.

Two things follow if you stay on the old files. Their settings rows are gone, so the frontmatter field list has no editor in the app, and a note cannot use a profile of your own until the conversion has run: ZotLit declines the note and asks you to convert the legacy templates first. The Profiles page shows no Add and no Import until the conversion has run, and every profile file action stays disabled; the quick-switch picker can still make a profile if you need one. Your default literature notes keep working exactly as they did.

If your two citation files use different languages, the fold is Liquid, the Eta file stays where it is, and ZotLit names the files that no longer affect citations.

Converting 2.1 template files has the steps and what each file becomes.

Export with citations stops on an unknown or ambiguous keyCopy anchor link

ZotLit: 导出带引文的笔记 now reads your note the way Pandoc does, so literal @citation-key text reaches the bibliography. A work you cite both by wikilink and by key gets one entry, nocite works, and a key inside code or behind an escape stays plain text.

The cost is that a key which matches no item in your library scope, or matches several, stops the whole export and names the keys. In 2.1 such a note exported with Pandoc's undefined-citation output and no reference list, which looked like success. Check the spelling in Zotero, or widen the library scope under Settings > ZotLit > Zotero. Export a note with citations covers the workflow.

The agent template commands are retiredCopy anchor link

Nine commands in ZotLit's obsidian CLI namespace now refuse every call and report the command as retired:

zotlit:template-schema, zotlit:template-render, zotlit:template-document-render, zotlit:template-source, zotlit:frontmatter-status, zotlit:frontmatter-eval, zotlit:frontmatter-set, zotlit:frontmatter-remove, zotlit:frontmatter-reorder.

An agent that wrote templates through them must move to zotlit:template-inspect, which reads a saved document and how current it is; zotlit:template-data, which lists fields with real values from an item; and zotlit:template-check, which renders every part and reports what fails. Frontmatter is edited in the profile document and checked with output=frontmatter. These are command line commands, not command palette entries. The Template Workbench CLI explains the loop, and the Template Workbench CLI reference lists every live command beside the retired one it replaces.

The settings tab is reorganizedCopy anchor link

• Maintenance is now Settings > ZotLit > 高级.
• The Database and Library pages merged into Settings > ZotLit > Zotero.
• The Live updates page became the 本地服务器 group on Settings > ZotLit > 高级, where 运行本地服务器 sits above 接收来自 Zotero 的更新.
• Note import is now Settings > ZotLit > 导入笔记.
• The Templates page is gone. 模板文件夹 and the 模板引擎 rows moved to Settings > ZotLit > 高级, and 引文文本 to Settings > ZotLit > 引文.
• 参考文献样式 moved to the main page, which now holds the default profile's rows.
• Auto-pair Eta tags has no toggle any more; the editor pairs tags as you type.

Row names are unchanged, so Obsidian's own settings search still finds a setting by the name you know. Where settings moved has the full table.

What's NewCopy anchor link

Imported notesCopy anchor link

Settings > ZotLit > 导入笔记 > 高亮映射

maps each Zotero highlight color on its own, to an emoji or to an HTML 标记, or to a 自定义 emoji you choose. See Import Zotero notes.

The emoji stay compatible with Obsidian 1.14's color highlights. With a custom mapping you can use more colors than native Obsidian offers, including Colorful Highlights.

Template data explorerCopy anchor link

The explorer is rebuilt on the workbench's own field browser. Fields are grouped into sections you can 展开所有分组 or 折叠所有分组, each row inserts itself with 插入字段 or copies it with 复制值, 复制路径, 复制输出, 复制（如果存在）, 复制循环, and 复制连接结果. The pane's menu saves the data as JSON: 导出所选论文数据 at a note root, 将模板数据保存为 JSON elsewhere. 选择条目 and 选择标注 switch which item or annotation the pane reads. See Explore template data.

Citations, references, and the suggesterCopy anchor link

• Hovering citations in a note retargets one popover instead of opening a card per citation, and the card follows the pointer from one citation to the next.
• Search results in the citation suggester read as one line: the venue in italics, and the volume and pages in their own form such as 3(2). A result from a group library is marked as such.
• When an imported note's profile or its citation style is unavailable, the References Sidebar says so and offers 切换配置方案… instead of dropping to a plain list.
• The suggester's footer now reads 插入替代引文 for the alternate form.
• A citation with a locator writes Pandoc's braced form, [@key, {p. 62}], in the raw source. The formatted text is unchanged.

See Insert citations and Review, copy, and troubleshoot references.

LaTeX citations in a templateCopy anchor link

tex_cite in Liquid, and texCite in Eta, write zt.citations as one LaTeX citation command, so a citation template reaches \cite{doe2024} or \autocite{doe2024} without a key loop of your own. The first item's prefix becomes the prenote, and its locator and suffix the postnote. See tex_cite and texCite.

One filter covers both formats Zotero Integration gave a command of its own, latex and biblatex. Migrate from Zotero Integration maps that plugin's Nunjucks templates, its persist blocks, and its citation formats onto profiles.

Batch update and importCopy anchor link

The confirmation for a vault-wide run now groups its rows by profile and says which items match no profile or several, which profiles are unavailable, and what happens to the notes you keep as they are. The import dialog names the notes that will arrive without a parent literature note before you confirm. See Keep notes up to date for a batch run, and Create and open literature notes for the profile a bulk run gives new notes.

Other improvementsCopy anchor link

• Links and menu commands from Zotero now name the profile they mean, so a note opens with the template you chose rather than the default. A profile ZotLit cannot find opens a prompt to pick one. See Protocol links.
• The Welcome view's settings link opens Settings > ZotLit > Zotero, and its folder picker explains how to navigate and choose.