README file from
Github[!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.
[!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.jsonLanguage Pack fromgithub.com/aidenlx/zotlit.
[!IMPORTANT] Shell command (macOS only) On macOS, ZotLit runs the system
cp -ccommand 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 systemcpcommand. 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
v1branch, with v1 docs.
Support
Questions, help, and bug reports: Community — Discord for chat, GitHub Discussions for ideas and bugs.
AGPL-3.0-or-later · Credits · Not affiliated with Obsidian or Zotero