Migrate from Zotero Integration

Use this guide when you currently use the mgmeyers Zotero Integration plugin and want to switch to ZotLit.

Install ZotLit

Existing notes

Zotero Integration notes are regular Markdown files. They stay in your vault and remain readable after the switch.

ZotLit identifies literature notes by a zotero-key frontmatter property. If your Zotero Integration notes already carry a Zotero key in frontmatter (and ZotLit can resolve it), ZotLit recognizes them. If not, treat them as standalone notes and create fresh literature notes through ZotLit.

ZotLit does not read Zotero Integration's %% begin notes %% / %% end notes %% persist markers. Those markers remain as inert comments in the file.

Translate templates

Syntax differences

Zotero Integration uses Nunjucks. ZotLit uses Liquid by default. The table below maps common Nunjucks constructs to their Liquid equivalents.

Data path changes

All template data in ZotLit lives under the zt variable. The table below maps Zotero Integration variables to their ZotLit equivalents.

The Template Data Explorer shows every available field for a live Zotero item. Use it to discover the ZotLit equivalent of any Zotero Integration variable.

The persist-to-managed-region shift

This is the most important conceptual difference between the two plugins.

• In Zotero Integration, {% persist "id" %} marks content to keep across re-imports. Everything outside persist blocks is re-rendered.
• In ZotLit, {% managed %}...{% endmanaged %} marks content to re-render on update. Everything outside the managed region is kept.

The model is inverted. Zotero Integration marks what to keep. ZotLit marks what to replace.

In Zotero Integration, you might have several persist blocks. In ZotLit, there is one managed region per note.

Zotero Integration template:

# {{ title }}
Authors: {{ authors }}

{% persist "notes" %}
{% if isFirstImport %}
- [ ] Read this paper
{% endif %}
{% endpersist %}

{% persist "annotations" %}
{% set newAnnots = annotations | filterby("date", "dateafter", lastImportDate) %}
{% for a in newAnnots %}
> {{ a.annotatedText }}
{% endfor %}
{% endpersist %}

ZotLit equivalent (profile note source):

The note body contains one managed region for generated content. Personal notes go outside the region.

# {{ zt.title }}
Authors: {% for c in zt.creators %}{{ c.fullName }}{% unless forloop.last %}, {% endunless %}{% endfor %}

{% managed %}
(Annotations and generated content go here. Re-rendered on every update.)
{% endmanaged %}

## My notes
(This section is never touched by updates. Write freely here.)
- [ ] Read this paper

The Annotation Section is a separate part of the profile document (after the --- zotlit:annotation --- header). It controls the format of one annotation:

> {{ zt.text }}

Key points:

• Personal notes that were inside {% persist "notes" %} move outside the managed region.
• The annotation loop moves into the profile's Annotation Section. ZotLit iterates over annotations automatically.
• isFirstImport and lastImportDate have no equivalent. The managed region re-renders all content on every update.
• All annotations render every time. Stale annotations are removed automatically.

Template includes

Zotero Integration's {% include "[[file]]" %} becomes ZotLit's shared partials. Create a zotlit-partial.<name>.md file in the template folder, then reference it with {% render "<name>" with zt as zt %}.

See Customize a template for the steps.

Citation formats

Zotero Integration registered one command per citation format. ZotLit renders every citation through the citation template, so the format is a filter choice inside that one document:

See tex_cite for the prenote and postnote rules, and for the inputs LaTeX has no slot for.

The citation template reads zt.variant to render two forms: the suggester inserts main on Enter and alt on Shift+Enter. One template therefore offers two of these formats at a time, where Zotero Integration gave each its own command.

formatted-citation and formatted-bibliography render through a CSL style rather than the template. ZotLit produces that output when it exports a note with citations.

Features with no direct equivalent

Features you gain

• No Better BibTeX dependency. ZotLit reads Zotero's database directly in a more performant way.
• Template Workbench. Live preview while editing templates, with the Data Explorer beside the editor.
• Profile match. Auto-select templates by item type, tags, or collections.
• Graph citations. Citation edges appear in Obsidian's graph view.
• Managed region. Your edits outside the region survive every update, with no special syntax.
• Profile switching. Change a note's template after creation.

See also