Zotero Completion

Search Zotero PDF attachments and annotations from Obsidian and insert a Markdown link at the cursor.

Features

• Searches annotations by comment or highlighted text.
• Searches PDFs by citation and filename.
• Inserts zotero://open-pdf/library/items/... links, including annotation page numbers.
• Persists the normalized Zotero cache in Obsidian's plugin data.
• Provides commands to refresh and clear the cache.
• Lets you configure the local API URL and retrieval limit.

Requirements

• Obsidian desktop 1.5.0 or newer.
• Zotero 7 or newer, running on the same computer.
• Zotero's local API enabled under Zotero → Settings → Advanced → Allow other applications on this computer to communicate with Zotero.

The plugin is desktop-only because it communicates directly with Zotero Desktop on the local loopback interface.

Install

Once the plugin is accepted into the Obsidian community directory:

1. Open Settings → Community plugins in Obsidian.
2. Select Browse and search for Zotero Completion.
3. Select Install, then Enable.

For beta testing before directory approval, install BRAT from Community plugins and add:

https://github.com/yuukibarns/obsidian-zotero-completion

Development

npm install
npm run build
npm test

Usage

Run Zotero Completion: Insert annotation or PDF link from the command palette. The first use fetches data from Zotero; later uses read the persisted cache immediately. Assign a hotkey from Settings → Hotkeys if desired.

Use Zotero Completion: Refresh annotation and PDF cache after changing your Zotero library, or Clear annotation and PDF cache to force a fetch on the next insertion.

Network and privacy

The plugin sends HTTP requests only to a loopback address (localhost, 127.0.0.1, or ::1). The default endpoint is Zotero Desktop at http://127.0.0.1:23119/api. Non-loopback API URLs are rejected.

It retrieves library item metadata, PDF attachment metadata, and annotation text, then stores a normalized cache in the vault's Obsidian plugin data. It does not modify the Zotero library. It has no telemetry, advertisements, account requirement, or requests to third-party services.

Troubleshooting

If refresh cannot contact Zotero, confirm Zotero is running and test its local API:

curl -i -H 'Zotero-API-Version: 3' \
  'http://127.0.0.1:23119/api/users/0/items?limit=1'

A working local API returns HTTP 200 and a JSON array.

Releasing

Push the source to a public GitHub repository, then tag the commit with the exact version from manifest.json (without a v prefix):

git tag 1.0.0
git push origin main 1.0.0

The release workflow builds and tests the plugin, then publishes main.js, manifest.json, and styles.css as GitHub release assets. Submit the repository URL through the Obsidian community directory; only the initial release requires review.

License

MIT © 2026 Jack Barnes