How to customize a template

Use the Template Workbench View to change a literature note's name, folder, properties, body, or annotation format, to change the text a citation inserts, or to share a piece of template text between profiles.

A profile is the document that authors one literature note. See Profiles for what a profile holds and how ZotLit chooses one. If your vault still holds 2.1 template files, Migrate from 2.1 templates folds them into profile documents first.

Edit a literature note profileCopy anchor link

The Template Workbench View supports Liquid, Eta, and JavaScript frontmatter fields. Eta and JavaScript fields require the JavaScript 模板 gate.

To return this template to its built-in form, select 恢复内置 on the same row. ZotLit moves the file to Obsidian's configured trash. You can recover it from there; existing notes keep their content until updated.

Customize the citation textCopy anchor link

The citation text is one template document, zotlit-citation.md, that renders every citation you insert. It renders both the main and the alternate citation from one source: zt.variant tells it which gesture asked for the citation.

Edits take effect on the next citation you insert. Existing citations in your notes are plain text and stay as written.

Restore the built-in citation textCopy anchor link

Once the document exists, the 引文文本 row also carries a rotate button, tooltipped 重置为默认值. It asks 重置引文文本？ and then moves your document to Obsidian's configured trash, where you can recover it. New citations use the built-in text again.

Share a piece of template text between profilesCopy anchor link

A partial is a template document that any other template renders by name. Write a line once, in zotlit-partial.<name>.md, and call it from every profile and from the citation text.

Create a partialCopy anchor link

Three ways, all of which name the file for you:

• Open Settings > ZotLit > 文献笔记配置方案 > 片段 and select 添加片段.
• Type {% render " or {% include " in a Liquid template, or include(" in an Eta one. The completion lists every partial in your vault and ends with 新建片段…. The new document opens in a split beside what you were editing.
• Select some template text, right-click it, and choose 提取为片段…. ZotLit moves the selection into the new document, leaves the matching call behind, and opens the new document in a split. In the template you extracted from, that is one undo step.

Name a partial with letters, digits, and hyphens. ZotLit trims the name, turns each run of spaces into a hyphen, and lowercases it, so Journal line becomes journal-line. Names are one flat list for your whole vault, and two partials cannot share a name regardless of case.

Five names belong to other ZotLit templates and are refused: filename, note, annotation, content, and citation. A file that takes one anyway registers nothing and gets a 片段名称已被占用 row in settings.

Call a partialCopy anchor link

In Liquid:

{% render "authors" with zt as zt %}

In Eta:

<%~ include("authors", zt) %>

In Liquid, the with zt as zt clause is not optional. The render tag opens an isolated scope, so a bare {% render "authors" %} cannot see the caller's zt: every zt output in the partial comes out empty, and only its literal text survives. Accepting a name from the completion list writes the clause for you.

Liquid's {% include %} tag renders a partial with access to the caller's variables, and needs no with clause. Use render when you want the partial's scope kept separate. See Calling a partial for the complete rule, and the Eta form for an Eta document.

Preview and edit a partialCopy anchor link

In a profile's tabs, with 源码 off, a call with a plain quoted name (Liquid render or include, Eta include(...)) is drawn as a Partial Placeholder: a compact control carrying the partial's name, the rest of the arguments as written, 预览片段, and 编辑片段. The preview arrow opens a read-only render of that partial below the line, using the data of the slice the call sits in. Put your cursor in the call and the placeholder turns back into plain source, so you can edit the arguments.

The five reserved names are never partial names, so none of them draws one: {% render "annotation" %} draws the annotation placeholder for the profile's annotation section, and a call on filename, note, content, or citation draws nothing. A call inside a fenced code block is prose about a call, and draws nothing either.

A partial has no data of its own, so its own editor asks you which caller to render as: 按笔记调用预览, 按标注调用预览, or 按引文调用预览, from the view's pane menu while the Preview panel is shown. It opens on Note and remembers your choice for that file.

Rename or delete a partialCopy anchor link

Renaming is an ordinary Obsidian file rename. ZotLit has no rename action and rewrites no calls, so every template that called the old name then marks its placeholder 缺失. Select that marker to read the problem in the editor's 问题 area, then edit the call or create the partial yourself.

To delete, open the partial's row at Settings > ZotLit > 文献笔记配置方案 > 片段, open its 更多操作 menu, and select 删除片段. ZotLit moves the file to Obsidian's configured trash and rewrites no callers.

A note that ZotLit writes through a template calling a partial your vault no longer holds is not written at all. ZotLit says which partial is missing and offers 打开模板工作台 to open the document holding the failing call.

See alsoCopy anchor link