ZotLit writes your Zotero library into an Obsidian vault as Markdown
Bring your Zotero library into Obsidian. Create literature notes, insert citations, and annotate PDFs without leaving your vault.
At a glance
- What is it?
- ZotLit is an Obsidian plugin paired with a Zotero companion that turns library items into Markdown literature notes, inserts citations, and surfaces Zotero annotations next to the editor. It reads the Zotero database directly and never writes to it, and the current 2.x line is a breaking rewrite with beta releases still in progress.
- Who is it for?
- Adopt ZotLit if you keep Zotero as the reference manager and Obsidian as the writing environment and you want literature notes that are plain Markdown in your vault, with citations and annotations reachable without switching applications.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 21, 2026, and from our analysis. They are not legal advice.
Editorial analysis
One command from a library item to a linked Markdown note
The problem ZotLit addresses is the gap between where you keep references and where you write. A Zotero library holds the item, the PDF, the highlights and the notes. Obsidian holds the argument you are building. Moving between them means copying citation keys, retyping highlights and losing the link between the two.
ZotLit connects the two. The README describes the scope in one line: one command turns a Zotero item into a Markdown literature note shaped by your template. The quick start is short because the design intends to be used inside the editor. With ZotLit installed, you open the command palette, run the create-note command, pick an item from the Zotero library, and the plugin writes a Markdown note with frontmatter, headings, highlights and your own notes, ready to link.
The audience is researchers and students who already live in Obsidian and keep Zotero as the reference manager, and who want their notes to remain ordinary Markdown files rather than a closed format. The word that matters in the README line is plain. Everything ZotLit produces stays as plain Markdown in your vault, which means the notes remain readable with any editor and remain yours if the plugin disappears.
Beyond note creation there is a citation search that runs inside the editor, a sidebar of highlights that follows the active Zotero reader, import of Zotero child and standalone notes, and a re-render path that refreshes notes and metadata when items change.
Two shipped apps: an Obsidian plugin and a Zotero companion
ZotLit is not a single artifact. The README badges refer to two separate packages, an Obsidian plugin version and a Zotero companion version, each with its own package.json under the apps/ directory of the repository. The manifest for the Obsidian side is the file the badge reads to show the plugin version, and the companion has its own.
The companion exists for one specific reason, and the features table says so directly: live updates, pushing changes from Zotero to Obsidian as they happen, requires the companion. Everything else in the table works without it. That is a useful design decision to understand before you install, because it determines whether you are adding one thing to Obsidian or two things to two applications.
The repository layout is a monorepo. The root package.json is marked private and drives work through turbo, with the Obsidian app built through a filtered turbo run:
"build:plugin": "turbo run build --filter=@zotlit/obsidian --output-logs=full",There are packages/ and apps/ directories, a pnpm workspace, a packageManager field pinning the exact pnpm release:
"packageManager": "[email protected]"and a turbo.json for task orchestration. The tooling is modern and opinionated: turbo for tasks, oxlint and oxfmt for linting and formatting, eslint for a separate review path that includes an Obsidian specific plugin, and lefthook installed through the prepare script so git hooks are set up on install. If you are contributing, that is the loop you will be in.
Templates decide the shape of every note, citation and filename
The template system is the heart of the extension, because it is what separates a generated file from a note the user actually wants. The features table lists templates as the ability to customize note, citation and filename output with Liquid or Eta templates. Two template languages are offered, which suggests the project is trying to serve two habits: one engine for people who already use Liquid elsewhere, and Eta for people who want something closer to a typed JavaScript template.
The consequences are worth spelling out. A template renders frontmatter, headings, highlights and note text into a Markdown file, so the structure of a literature note is a file you can edit, version and share. The filename is a template too, which means a note's name can be derived from the item metadata rather than typed by hand.
The features table also lists agent-assisted templates, where you describe the note you want and an agent edits and tests templates against your Zotero library. The repository backs this up with an install-skill page and a skills/ directory at the root, alongside .agents/, .claude/ and .codex/ directories and files such as AGENTS.md, CLAUDE.md and CONTEXT-MAP.md. In other words, the project ships prompt and context files for coding agents as part of the source tree. That is a deliberate choice about how templates are expected to be written, and it also means the plugin can be driven by an assistant rather than only by hand.
The trade-off is that a template engine makes the output reproducible only as long as the template and the item metadata are both under your control. When Zotero metadata changes, the same command produces a different note, which is exactly what the re-render feature is for and also exactly the thing to think about before you automate it across a large library.
Reading the Zotero database directly, without writing to it
The disclosure section is the most technically interesting part of the README, and any team evaluating ZotLit should read it before installing.
ZotLit reads the Zotero database directly, including files stored outside the Obsidian vault: Zotero's data directory, attachments on external drives or on cloud storage. It reads only and does not write to the Zotero database. That is a meaningful design choice, because it avoids the alternative of asking Zotero to export on demand, and it means the plugin sees everything Zotero holds, not just the synchronised subset.
The safe snapshot mechanism is described as well. When the Zotero data directory sits on a different drive from the system temp folder, ZotLit keeps its short-lived database snapshots in a .zotlit-db-reads folder inside that data directory, and that folder can be deleted at any time. The reason for the snapshot is explained in the same README section: it lets the database be read safely without interfering with Zotero while it is running.
On macOS, the snapshot and the attachment import use the system cp -c command to create zero-copy clones, which duplicate a file instantly without using extra disk space because macOS shares the underlying data until one copy changes. The README is explicit that Node.js does not expose that feature directly, so the system command is invoked, and that no other shell commands are executed. That is a macOS only path, and it is worth knowing before you read a file copy on a non Apple system.
Live updates run on localhost, and the language pack comes from GitHub
The second disclosure covers the network. Live updates run a local notification server so the Zotero companion can push changes to Obsidian. Connections stay on your machine, on localhost, and the README states that ZotLit does not send data to any external service.
That is a local server, but it is a server, and it exists only when the companion is installed. Users who only want the create-note command and the citation search do not need it, and users who do install it should understand that a notification endpoint is listening locally.
There is one outbound download, and it is conditional on consent. After you consent, ZotLit downloads the zh-CN.json Language Pack from github.com/aidenlx/zotlit. The messages/ directory at the repository root holds the translations, and the download is tied to your consent, which is the pattern the project uses for anything that leaves the machine.
The macOS shell command, the localhost server and the consented language pack download are the three points where ZotLit touches something outside the vault. All three are disclosed in the README, which is a good sign, and all three are reasons to read that section rather than skim it. The remaining features, note creation, citation insertion, annotation display, note import and re-rendering, work locally on files you already control.
The Obsidian installer version is a hard gate, and v2 is a rewrite
Two constraints will decide whether your first attempt works, and both are called out in warning blocks at the top of the README.
The first is the Obsidian installer version. 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, and the README says to check the current version under Settings and About. If the installer is older, ZotLit does not load, Obsidian reports that it failed to load the plugin, and the developer console shows a SyntaxError. The fix given is to download Obsidian from obsidian.md/download and run it over the current installation, with the note that nothing is deleted and no notes are lost. This is a specific, checkable condition, and it is the first thing to verify if the plugin does not appear.
The second is the version jump. The README states that v2 is a major upgrade with breaking changes, that existing literature notes and custom templates do not carry over unchanged, and that the migration guide should be read before upgrading. The v1 codebase stays available on the v1 branch with its own documentation site, which is a sensible escape hatch for users who are not ready to rewrite their templates.
The release tags show where the project currently is. The most recent releases are 2.2.0-beta.3 on 2026-10-11, a matching resource release named res-2.2.0-beta.3, and 2.2.0-beta.2 on 2026-10-01. The beta suffix is the honest signal here: this line is still settling, and the last push was on 2026-10-19.
AGPL-3.0-or-later, and the cost of a plugin in your notes app
ZotLit is licensed AGPL-3.0-or-later. The package.json root records the same licence, and the LICENSE file and a NOTICE file sit at the repository root. The README footer repeats the licence identifier and adds that the project is not affiliated with Obsidian or Zotero.
For an end user who installs a plugin and writes personal notes, the AGPL is not the deciding factor. It is the deciding factor for anyone who reads the code, runs it as a service, or builds on it, and for that group the copyleft obligations are the thing to read about. A company that distributes ZotLit inside another product has a different question to answer than a person with a personal vault, and the licence text is where that answer lives.
The repository is also unusually open about its own fragility. The README calls ZotLit a third-party project, not affiliated with Obsidian or Zotero, says it may break when either updates, and tells you to back up your vault and your Zotero data before using it. The placement of that warning is deliberate. A plugin that writes into your notes, backed by a third party application you do not control, is a dependency in the practical sense even when the vault format is plain Markdown.
Support runs through a community section on the project website, with Discord for chat and GitHub Discussions for ideas and bugs, rather than through a ticketing system, and the project publishes a credits page alongside the documentation.
Editorial conclusion
Adopt ZotLit if you keep Zotero as the reference manager and Obsidian as the writing environment and you want literature notes that are plain Markdown in your vault, with citations and annotations reachable without switching applications. Do not adopt it if you are still on ZotLit v1 and your templates are not worth rewriting, since the migration guide is explicit that v2 has breaking changes, and do not adopt it on a shared or restricted machine without reading the disclosures, because it reads the Zotero database including files outside the vault. Before you install, check the Obsidian installer version in Settings and About, because the README states that an installer older than 1.13.4 makes the plugin fail to load, and read the Zotero database and network disclosures so the .zotlit-db-reads snapshots and the localhost notification server are expected rather than surprising.
Frequently asked questions
How do I create a literature note with ZotLit?
With ZotLit installed, open the command palette, run the create-note command and pick an item from your Zotero library. The plugin writes a Markdown note with frontmatter, headings, highlights and your own notes, shaped by your template.
Does ZotLit write to my Zotero database?
No. The README states that ZotLit reads the Zotero database directly and only, including files stored outside your vault, and never writes to it. Short-lived database snapshots are kept in a .zotlit-db-reads folder inside the Zotero data directory and can be deleted at any time.
Do I need the Zotero companion to use ZotLit?
Only for live updates, which push changes from Zotero to Obsidian as they happen. Note creation, citation insertion, the annotation sidebar, note import and re-rendering work without the companion.
Why does ZotLit fail to load in Obsidian?
The most common cause given in the README is an Obsidian installer older than 1.13.4, since the in-app update does not replace the installer. Obsidian then shows that it failed to load the plugin and the developer console shows a SyntaxError. Check the version under Settings and About.
What breaks when moving from ZotLit v1 to v2?
The README describes v2 as a major upgrade with breaking changes, and says existing literature notes and custom templates do not carry over unchanged. It points to a migration guide, and the v1 codebase remains available on the v1 branch with separate v1 documentation.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/aidenlx-zotlit)Was this useful?