README file from
Github[!WARNING] Update the Obsidian installer first. ZotLit needs Obsidian 1.14.5 or newer, and the installer version must also be 1.14.5 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 lets Zotero manage your papers, PDFs, and annotations, and keeps Obsidian for your thinking and writing. Browse your library in an Obsidian tab and query its items, annotations, and attachments, read and annotate a paper's PDF beside your draft, turn what you read into literature notes and citations, and export the finished note to Word with a bibliography. Your notes stay as plain Markdown in your vault.
Features
| Feature | Description |
|---|---|
| Library View | Browse your Zotero collections and tags in an Obsidian tab. Select a paper to see its abstract, its PDF, and how many highlights you made in each color. |
| ZotLit Query | Ask questions of your Zotero library without leaving Obsidian: every highlight in a collection, the papers from one journal, the papers tagged for a chapter. See the answers as tables, cards, or lists, and add columns of your own. |
| PDF reader | Read a paper beside your draft. With Zotero 10, the highlights and comments you make in Obsidian save to Zotero and sync to your other devices. |
| Annotation view | See all of a paper's highlights in one list beside the PDF. Drag one into your note, and it becomes a quote that links back to its page. |
| Literature notes | Create a note for a paper in one step, with its details, your highlights, and a link back to Zotero. |
| Citations | Cite as you type, and see the reference list in your citation style, such as APA or Chicago, as you write. |
| Export | Export your draft to Word with its citations and reference list already formatted. |
| Citation graph | See in Obsidian's graph view which papers each note cites, and which papers your notes have in common. |
| Note import | Bring the notes you wrote in Zotero into your vault. |
| Keep notes updated | When you correct a paper's details in Zotero, update its note with one command. |
| Templates | Choose what each note contains and where it goes. Use a different layout for books, articles, or a project, and see a live preview as you edit. |
| Agent-assisted templates | Describe the note you want in plain words, and your AI assistant builds and tests the template for you. |
Full guides live in the documentation.
Quick start
With ZotLit installed, open the command palette and run ZotLit: Open Zotero library. The Library View shows your collections and papers. Select a paper to see its abstract and annotations, double-click it to read its PDF in Obsidian, or drag it into a note to cite it.
When you have something to say about a paper, run the create-note command. 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 never writes to the database file. Changes you make from Obsidian, such as PDF annotations, go through Zotero's local API, and only after you grant permission in Zotero. 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-readsfolder 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.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