Zotero Reference: a PDF reference extractor for Zotero, not a reference manager

What Zotero Reference actually does, and who it is for

Zotero Reference is a Zotero add-on that reads the reference list of a PDF and turns each entry into something you can act on inside Zotero. The README describes the plugin's role plainly: it does not produce data, it moves data. The sources it can draw from are the PDF itself, readpaper (title search), Crossref (title and DOI search), Semantic Scholar (DOI search) and arXiv (arXiv ID search).

That framing matters, because the name invites a wrong expectation. This is not a reference manager. Zotero is the reference manager; this add-on is an extractor and a linker that sits on top of it. The people who get value from it are researchers who already keep their PDFs in Zotero and want the citations inside those PDFs to become items in the same library, without retyping them. The README also notes that Chinese-language support was added, with CNKI named as a covered source, which suggests the author's audience includes readers of Chinese journals and theses.

If you want Zotero to format citations in Word, or to build a bibliography in APA style, this plugin is not the thing doing that work. Zotero is.

How the parsing and linking mechanism works

The add-on exposes a floating panel above the reader. Across the top of that panel are small dots, and each dot is a data source. Clicking a dot switches the source. The README states that the first click parses or fetches the current PDF's references from the priority source configured in the preferences, and that clicking again switches to another source. Long-pressing skips the local cache if one exists for that PDF and re-parses from scratch; the README says this applies to all sources.

There is a second mode that matters for long documents. Holding Ctrl while clicking or long-pressing parses references backward from the current page. The README limits this to the PDF source and says it does not work for API sources. The intended use is theses and dissertations, and the instructions say you should scroll to the page containing the last reference before triggering it. That is an honest admission of how the parser works: it walks the document rather than understanding it.

Once entries appear, clicking the blue area copies the reference text including identifiers such as the DOI. Long-pressing the blue area opens an edit dialog, and the README recommends editing Chinese references to trim entries and improve import success. Clicking the plus sign adds the reference to every folder the currently open document belongs to and creates a two-way link; Ctrl+clicking the plus sign adds it to the folder selected in the Zotero main pane instead. Clicking the minus sign removes the two-way link but leaves the item in My Library.

Installing the add-on and running a first parse

The add-on is distributed as an XPI file. The package.json in the repository points its release page at the latest download, and the README's badge links to the releases page on GitHub. The install path is the standard Zotero one for third-party add-ons: download the .xpi from the releases page, then in Zotero open Tools, then Add-ons, and install it from the file. The repository does not document a command-line install.

If you want to build it from source instead, the repository is a TypeScript project driven by npm scripts. The build script and the type check are separate, and the combined build runs both.

npm install
npm run build

The README's first-use advice is to open the preferences and configure them before parsing anything. Four settings are named there: whether to fetch references automatically when a document is opened, which item types to exclude from that automatic fetch, which source to try first on the initial click, and whether Ctrl+click on a floating abstract title should translate it through the zotero-pdf-translate plugin. The exclusion field takes English item type names separated by commas. The README lists the full set, including journalArticle, thesis, conferencePaper, preprint, book and bookSection.

After configuring, open a PDF in the Zotero reader and click the refresh control once. You should see a count such as the "31 references" label the README shows, with the source dots along the top of the panel. Clicking a dot moves you to a different source if the first one returned nothing useful.

Where the PDF parser breaks down

The dependency on the PDF is the main limitation, and the README does not hide it. The project keeps a dedicated issue thread titled as a feedback channel for PDF parsing failures, which is a reasonable indicator that failures are expected rather than exceptional. Two-line reference lists, multi-column layouts, and reference sections that run across many pages all stress a parser that is walking text rather than reading structure.

The Ctrl+click backward-parsing mode exists precisely because the parser does not reliably find the reference section on its own in long documents. The instruction to scroll to the last reference page first is a manual workaround, and it only applies to the PDF source. API sources behave differently: they search by title or DOI, so they can only resolve references that are indexed somewhere, and they cannot help with an unpublished or unindexed citation.

There is also a stated compatibility problem. The README says the plugin's automatic association feature is not compatible with the scihub plugin. If your workflow depends on that plugin, the linking behavior here will conflict with it. Beyond that, the README does not document rollback, does not describe what happens to already-linked items if you disable the add-on, and does not give a recovery path for a bad batch import. Those gaps are worth knowing before you let it run automatically on a large library.

Zotero Reference compared with doing it by hand or with a DOI lookup

The realistic alternative is not another Zotero add-on; it is the manual route. You read the reference list, copy a DOI, paste it into Zotero's Add Item by Identifier box, and let Zotero fetch the metadata. That path is slower per reference but it is deterministic: you decide what gets added, and the metadata comes from a resolver rather than from text extraction.

The difference in approach is where the data comes from. Zotero Reference starts from the rendered text of the PDF and tries to recover structure from it, then optionally falls back to title or DOI search against Crossref, Semantic Scholar, arXiv or readpaper. Add Item by Identifier starts from an identifier you supply and never guesses. For a clean DOI on a well-typeset paper, both end up in roughly the same place. For a scanned or unusually formatted bibliography, the identifier route is the one that will not silently produce a wrong entry.

The add-on's advantage is volume and the two-way link. Adding a reference through the plus sign associates it with the folders the current document belongs to, which the manual route does not do in one step. If you are processing a thesis with two hundred references, that difference is the whole argument for the plugin. If you are adding three references, it is not.

Maintenance, releases and the AGPL-3.0 licence

The repository is not archived. Its last push was on 2026-03-27, which is the same date as the 1.7.2 release, whose notes mention saving parsing results and AI parsing. The two releases before that were 1.6.7 on 2025-12-01, fixing reference text parsing, and 1.6.4 on 2025-11-10, fixing a broken OpenAlex path. The cadence is irregular and driven by breakage: two of those three releases are fixes for extraction or for an external source that stopped working.

That pattern is the real upgrade cost. Because the add-on depends on Crossref, Semantic Scholar, arXiv, readpaper and readcube, a change on any of those services can break a source without anything changing in this repository. The 1.6.4 note about OpenAlex failing is exactly that scenario. Expect to update the XPI when a source you rely on stops returning results.

The licence is AGPL-3.0, stated in the repository and as AGPL-3.0-or-later in package.json. The practical implication for most users is none: you install an XPI and use it. It matters if you intend to modify the add-on and distribute it, or to run a modified version as a network service, because the AGPL's source-availability condition reaches network use in a way that permissive licences do not. This is a description of the licence, not legal advice; if you plan to redistribute a modified build, read the LICENSE file and take your own advice.

Editorial conclusion

Adopt it if you read a lot of PDFs whose reference lists you want as Zotero items, especially Chinese-language literature, and you accept that parsing quality depends on the PDF and that the automatic association feature conflicts with the scihub plugin. Do not adopt it if you want a reference manager, a Word citation workflow, or a tool that produces bibliographies; Zotero itself does that, and this add-on only moves reference data into your library. Before relying on it, check the release notes for the version you install, confirm which source is set as the first-click priority in the preferences, and test the Ctrl+click page-backward parsing on one thesis-length PDF.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. MuiseDestiny/zotero-reference on GitHub
4. README
5. Releases