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 templates gate.

To return this template to its built-in form, select Restore built-in 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 Citation text row also carries a rotate button, tooltipped Reset to default. It asks Reset citation text? 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 > Literature note profiles > Partials and select Add partial.
• 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 New partial…. The new document opens in a split beside what you were editing.
• Select some template text, right-click it, and choose Extract to partial…. 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 Reserved partial name 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 Source 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, Preview partial, and Edit partial. 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: Preview as called from Note, Preview as called from Annotation, or Preview as called from Citation, from the preview pane menu. 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 Missing. Select that marker to read the problem in the editor's Problems area, then edit the call or create the partial yourself.

To delete, open the partial's row at Settings > ZotLit > Literature note profiles > Partials, open its More actions menu, and select Delete partial. 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 Open template workbench to open the document holding the failing call.

See alsoCopy Anchor Link