Zotero

Suzuri reads your Zotero library through the local API built into Zotero. You don't need an add-on, an API key or an exported .bib file. Zotero just has to be running on the same computer.

Setup

Citing from Zotero

The citation picker searches two sources as you type:

• Project: entries already in your project's .bib files. These show first and appear straight away.
• Zotero: top-level items whose title, creators or year match. They appear after a short pause once the query is two characters long, up to 20 at a time, most recently modified first.

If a Zotero item is already in your project, the picker leaves it out of the Zotero results. It counts as already in the project when it has the same citation key or the same title. That way you cite the existing entry instead of adding it a second time.

When you pick a Zotero item, Suzuri does three things before it inserts the citation:

1. Fetches the entry as BibLaTeX from Zotero.
2. Appends it to the project library (refs/refs.bib by default) under a key that won't change later (see below). Entries already in the file stay exactly as they are, including hand edits and odd spacing. If the library doesn't parse, for example because you're halfway through editing it, Suzuri stops without writing to it.
3. Copies the PDF, if the item has one, next to the library as <key>.pdf. Suzuri drops the file field from the entry, because it points at a path in your Zotero storage that only exists on this machine. A PDF that's missing or can't be read is logged, and the citation goes in anyway.

You can select several items at once, from either source, to insert them in one citation.

After this the project doesn't depend on Zotero. Pandoc, LaTeX, Typst and Suzuri all read refs.bib directly. Another person can clone the project and build it without Zotero, and closing Zotero doesn't affect citations you've already written.

Citation keys

Zotero stores a citation key for each item, but Zotero never generates one. Suzuri picks the key once, when the entry is first added, and never changes it:

• If Better BibTeX has given the item a key, and that key works everywhere, Suzuri keeps it. Citations you wrote in other tools keep working.
• Otherwise Suzuri makes one from the first author's surname, the year and the first meaningful word of the title, such as vaswani2017attention. Accented letters become their plain form (Müller becomes muller), and words like "a", "the" and "of" are skipped.
• If that key is already taken, Suzuri adds a letter: vaswani2017attentiona, then …b, and so on.

A key "works everywhere" when pandoc, Typst and BibTeX all accept it as is: only ASCII letters and digits, with _ or - allowed in the middle but not at the start or end. Better BibTeX keys sometimes end in a period or contain a slash, which breaks Typst. Suzuri doesn't use those keys and makes its own instead.

Opening the PDF

Put the cursor on a cite key and press Cmd+Alt+O. Suzuri opens refs/<key>.pdf in a split, in its own PDF viewer, so you can read the source next to your draft.

The file is Suzuri's copy, not the one in Zotero's storage. Annotations you make in Zotero's reader don't show up in it, and changes to it don't go back to Zotero. If an item had no PDF when you cited it, attach one in Zotero and save it as refs/<key>.pdf yourself. Suzuri doesn't copy it again for an entry that's already in the library.

Troubleshooting

The picker's footer shows what went wrong with Zotero. If Zotero couldn't be reached, the footer message says why.

Some other things you might see:

• "No PDF for @key in refs/." when you press Cmd+Alt+O means the item had no PDF attachment in Zotero, or Zotero couldn't locate the file. Linked files that have moved, and attachments stored only online, are common causes.
• A Zotero item you expect isn't listed. The picker only searches top-level items by title, creator and year. It doesn't search notes, attachments, tags or full text.
• A new entry wasn't written. Check that refs.bib still parses. Suzuri won't write to a library it can't read.