Sync references from Zotero

Keep your Zotero references in your LaTeX project without exporting anything by hand. Link your Zotero library, or one collection, to a .bib file, press Sync whenever you want the latest references, and cite them with \cite{...} like any other BibTeX file.

Plan

Reference manager sync is part of Luzbase Pro. On a plan without it, the Connect and Link a library buttons open the upgrade dialog instead. See Plans and limits.

How the sync works

• One way, from Zotero to Luzbase. Luzbase only reads your library. Nothing is ever written back to Zotero.
• Manual. A sync runs only when someone presses Sync. Nothing syncs in the background, and there is no schedule.
• Into one .bib file on one branch. Each linked library or collection has its own .bib file. A sync rewrites that file on the branch you have open in the editor.
• The whole file is rewritten every time. The file starts with a comment saying it is managed by Luzbase. Don’t edit it by hand, because the next sync replaces your edits. Change the reference in Zotero instead.
• Citation keys stay the same between syncs. You can keep citing the same keys after every sync.

Connect your Zotero account

1. Open your avatar menu and click Profile, then click Reference managers in the account settings menu. You can also go straight to luzbase.com/account/integrations.
2. Next to Zotero, click Connect.
3. Zotero opens and asks you to allow access. Approve it.
4. You come back to Luzbase and see “Zotero is now connected.” The row now shows a Connected badge.

Finish the round trip within 10 minutes. If it takes longer, or you cancel at Zotero, Luzbase shows Could not connect Zotero. Click Back to reference managers and start again.

Tip

You can also connect from inside a project. In the Link a library dialog described below, click Connect Zotero, and you return to the same page afterwards.

Link a library to your project

You need to be an editor or the owner of the project.

1. Open the project in the editor.
2. Click References in the editor header. On narrow screens the button shows only a book icon.
3. Click Link a library, or + Link if the project already has a linked library.
4. Fill in the dialog:
   • Reference manager: choose Zotero. This field appears only when you have connected both Zotero and Mendeley.
   • Library: My Library is your personal library. Zotero groups you belong to appear as “name (group)”.
   • Collection: Whole library, or one collection. Subcollections are listed indented under their parent.
   • File in the project: the .bib path to write. The default is references.bib. If another linked library already uses that name, Luzbase suggests one based on the collection name.
5. Click Link and sync. Luzbase links the library and runs the first sync straight away.

You can also link from the project page: open Settings, then References, and click Link a library. The button there reads Link, and it doesn’t sync. Open the editor’s References panel and press Sync to fill the file.

Pick a new file name

If a text file already exists at the path you choose, the first sync replaces its contents with your Zotero references. To keep a .bib you wrote by hand, give the synced file a different name, for example zotero.bib. You can use more than one .bib file in the same document.

Sync to get the latest references

1. In the editor, click References.
2. Under Linked libraries, click Sync next to the library.
3. When it finishes, a message tells you what changed, for example “references.bib: 2 added, 1 updated.” or “references.bib: already up to date.”

The sync writes into the branch you’re on. The panel says which one: “Syncing writes into the main branch.” Each linked library shows when it was last synced, or the error from the last attempt.

The synced file lands in the branch’s live copy, the same as an edit you type. Everyone on that branch sees it at once. It becomes part of your history the next time you save a version.

What a sync brings in:

• New items in the library or collection are added.
• Changed items are updated.
• Items you delete in Zotero or move to the Zotero trash are removed.
• With a collection linked, items you take out of that collection are removed.
• Only items filed directly in the linked collection are included. Items that sit only in one of its subcollections are not.

Use the file in your document

Point your document at the synced file the way you would with any .bib file. With biblatex:

\usepackage[style=authoryear]{biblatex}
\addbibresource{references.bib}

% ... in the text
Symmetries and conservation laws are linked by \textcite{noether1918}.

\printbibliography

With BibTeX and natbib, leave out the .bib extension:

\bibliographystyle{plainnat}
\bibliography{references}

For more on styles and commands, see Bibliographies.

Cite from the References panel

Once a library has synced, the References panel lists its entries.

1. Click References in the editor header.
2. Type in Search by key, title or author to find an entry.
3. Click the entry. Luzbase inserts \cite{key} at your cursor.

If the open file can’t take text, for example when an image is open, clicking an entry copies its key instead. The list shows the first 100 matches, so search to narrow it down.

Citation keys

Luzbase picks each entry’s key in this order:

1. The key you set in Zotero’s Citation Key field.
2. A Citation Key: ... line in the item’s Extra field, which Better BibTeX and similar tools add.
3. Otherwise, a key that Luzbase generates for the item.

An entry keeps its key from one sync to the next unless you set a different key in Zotero. A key once used for one item is never given to another item, even after the first item is deleted.

Working with collaborators

• Any editor or owner of the project can press Sync on a linked library. Viewers can browse and search the references but can’t sync or link.
• The sync reads Zotero through the account of the member who linked the library. That member’s plan must include reference manager sync. If it doesn’t, the sync fails with “The plan of the member who linked this source does not include reference manager sync.”
• If the member who linked the library leaves the project or becomes a viewer, the sync stops working. Unlink the library and link it again from your own account.
• On a protected branch, only the owner can sync. Everyone else should switch to their own branch first. See Branches.
• Archived projects can’t be synced.

Unlink a library from a project

Unlinking stops the sync but keeps the file.

1. On the project page, open Settings, then References.
2. Click Unlink next to the library. You see this button if you linked the library or if you own the project.
3. Confirm with Unlink.

The .bib file stays in the project as an ordinary file, and you can edit it freely. You can link the library again at any time.

Disconnect Zotero

1. Go to Account settings → Reference managers.
2. Click Disconnect next to Zotero.
3. Confirm with Disconnect.

Every library you linked through your Zotero account is unlinked from every project. The .bib files already in your projects stay as they are. Luzbase also asks Zotero to delete the access key it was using. You can disconnect at any time, even if your plan no longer includes sync.

If a row shows Reconnect needed, Zotero no longer accepts Luzbase’s access, for example because you removed the key in Zotero. Click Reconnect to fix it.

Limits

Limit	Value
Size of one synced .bib file	1 MB. A bigger library fails with “this library is too large for one .bib file; link a collection of it instead”.
Items read in one sync	50,000
Syncs per person	60 per hour
Syncs at once	One per linked library. A second one gets “this source is already syncing”.
Entries shown in the panel	The first 100. Search to find others.

If a sync fails

Message	What to do
“the Zotero connection was revoked; reconnect it under Account › Reference managers”	Go to Reference managers and click Reconnect.
“the linked collection no longer exists in Zotero; unlink this source and link another”	The collection was deleted in Zotero. Unlink it and link another collection.
“Zotero asked us to slow down; try again in a little while”	Wait a few minutes, then sync again.
“Zotero took too long to answer; try again” or “Zotero could not be reached; try again”	Try again later.
“path exists on this branch and is not a text file”	Choose a different file name when you link the library.

A large sync can take longer than the page waits for. When that happens, Luzbase keeps checking for up to two minutes and then shows “path is up to date.” or the error.

Related

• Sync references from Mendeley
• Bibliographies
• Save a version
• Plans and limits