aidenlx/zotlit

[!WARNING] Update the Obsidian installer first. ZotLit needs Obsidian 1.13.4 or newer, and the installer version must also be 1.13.4 or newer. Obsidian's in-app update does not replace the installer. Check yours in Settings → About.

If the installer is older, ZotLit does not load. Obsidian shows Failed to load plugin "zotlit", and the developer console shows a SyntaxError.

Fix: download Obsidian from obsidian.md/download and run it over your current installation. Nothing is deleted, and no notes are lost. Full steps →

[!NOTE] Coming from v1? v2 is a major upgrade with breaking changes. Your existing literature notes and custom templates do not carry over unchanged. Read the migration guide before upgrading.

Overview

ZotLit connects your Zotero library to Obsidian. One command turns a Zotero item into a Markdown literature note shaped by your template. You can search the library and insert citations without leaving the editor, and read your Zotero annotations in a sidebar that follows the active reader. Everything stays as plain Markdown in your vault.

Features

Feature	Description
Literature notes	One command turns a Zotero item into a Markdown note, shaped by your template.
Citations	Search your library and insert citations without leaving the editor.
Annotation view	A sidebar of highlights and notes that follows your active Zotero reader.
Note import	Bring Zotero child and standalone notes into your vault as Markdown.
Keep notes updated	Re-render notes and refresh their metadata as items change in Zotero.
Live updates	Push changes from Zotero to Obsidian as they happen. Requires the companion.
Templates	Customize note, citation, and filename output with Liquid or Eta templates.
Agent-assisted templates	Describe the note you want. Your agent edits and tests its templates against your Zotero library.

Full guides live in the documentation.

Quick start

With ZotLit installed, open the command palette and run the create-note command. Pick an item from your Zotero library, and ZotLit writes a Markdown note shaped by your template: frontmatter, headings, highlights, and your own notes, ready to link.

New here? Follow the first-note tutorial →

Disclosures

[!IMPORTANT] Zotero database access ZotLit reads your Zotero database directly, including files stored outside your Obsidian vault (Zotero's data directory, attachments on external drives or cloud storage). It reads only and does not write to your Zotero database. When your Zotero data directory sits on a different drive than your system temp folder, ZotLit keeps its short-lived database snapshots in a .zotlit-db-reads folder inside that data directory, which you can delete at any time.

[!IMPORTANT] Network use Live updates run a local notification server so the Zotero companion can push changes to Obsidian. Connections stay on your machine (localhost); ZotLit does not send your data to any external service.

After you consent, ZotLit will download the zh-CN.json Language Pack from github.com/aidenlx/zotlit.

[!IMPORTANT] Shell command (macOS only) On macOS, ZotLit runs the system cp -c command to create zero-copy clones of files. A zero-copy clone duplicates a file instantly without using extra disk space — macOS shares the underlying data on disk until one copy is changed. ZotLit uses this for two things: snapshotting the Zotero database so it can be read safely without interfering with Zotero, and importing attachments (PDFs, images) into your vault without doubling disk usage. Node.js does not expose this macOS feature directly, so ZotLit invokes the system cp command. No other shell commands are executed.

[!IMPORTANT] Third-party project: back up your data ZotLit is a third-party project, not affiliated with Obsidian or Zotero, and may break when either updates. Back up your vault and Zotero data before using it. The v1 codebase remains on the v1 branch, with v1 docs.

Support

Questions, help, and bug reports: Community — Discord for chat, GitHub Discussions for ideas and bugs.

---