How references work

This page explains how a reference source becomes a citation in your document. Everything here applies to LaTeX and Typst projects alike. For the setup steps, see Connecting Zotero, Mendeley, and DOI lookup.

The aggregated library

Typeward keeps one BibTeX file per project and writes every connected source into it:

<project>/.typeward/citations/library.bib

Because that file is an ordinary .bib file in your project, everything downstream sees plain BibTeX: the compiler, the language servers, and any other tool you point at it.

Reference sources

Four sources feed the library, and every one of them ships in every build, for everyone.

Source	What it reads	What it needs
Zotero (local)	The Zotero desktop app on this machine, over `127.0.0.1:23119`	Zotero 7 running
Zotero Web API	Your zotero.org libraries	A read-only API key you create yourself
Mendeley	Your Mendeley library, folders included	An OAuth sign-in
DOI and arXiv lookup	One entry per DOI or arXiv ID	No account, but the Refs tab, which appears only once a reference manager is configured

Zotero (local) needs no login and works with plain Zotero 7. The Better BibTeX plugin is optional, and it gives stable, human-readable citation keys. Use Zotero Web API when the desktop app is not running, or when it lives on another machine. Both Zotero sources can be enabled at once.

Mendeley Desktop was discontinued in 2022 and the API is in maintenance mode, so Mendeley exists mainly for migration. Entries from a DOI or arXiv lookup land in .typeward/citations/local.bib, beside the aggregated file, and merge into it with everything else.

Credentials and network access

There is no account of any kind, and no Typeward server in the picture. The services you connect use your own credentials, which Typeward stores in the OS keyring and never writes into settings.json. Nothing is switched on by default. Until you enable a source under Settings → Integrations → References, the reference features send nothing off your machine. Opening that card does probe Zotero over loopback on 127.0.0.1:23119, so each row can show whether the desktop app is reachable. That probe runs whether or not the switch is on, carries no credential, and never leaves your machine.

Zotero (local) works offline, because it talks to the desktop app over loopback. Zotero Web API, Mendeley, and DOI and arXiv lookup need the network. The generated library.bib and local.bib live inside the project, so compiling a document that cites them needs no network. Privacy and network behavior lists every host the reference features are allowed to contact.

How Typeward assembles the library

A refresh asks every configured source for its full export, then merges the results in the order the sources were registered. After a restart, with everything already configured, that order is:

Zotero (local)
Zotero Web API
Mendeley
DOI and arXiv lookups, from local.bib

DOI and arXiv lookups always merge last. The reference managers take the order they were switched on, so a manager you enable mid-session joins the end of the manager list until you restart Typeward.

The first occurrence of a citation key wins. In the order above, a key present in both Zotero and Mendeley keeps the Zotero entry, and Typeward drops the later copy.

The file opens with a generated header that records where the entries came from:

% Auto-generated by Typeward. Do not edit by hand; edits will be
% overwritten on the next library refresh.
%
% Source providers:
%   - zotero-better-bibtex: 214 entries
%   - doi-local: 3 entries
% Skipped 2 duplicate keys.

Entries you want to maintain yourself belong in a .bib file of your own, next to your document, which Typeward never touches.

The Refs tab

The Refs tab in the sidebar browses the sources you have connected. It appears once at least one source is configured. It disappears only after Typeward has proven that every configured source is unreachable (Zotero enabled but not running, for example). The sidebar then falls back to Files.

The panel holds these controls:

A reference manager selector, with the placeholder Select a reference manager…. Typeward offers only reachable managers, and hides the selector when one manager is configured. The manager names read Zotero (local), Zotero (account 1234567), and Mendeley (Your Name).
A combined library and folder tree, which appears only after you pick a manager. Its placeholder reads Loading libraries… while the libraries arrive, then Select a library…. Libraries appear immediately, and each library’s folders merge into the tree as they load. The tooltip shows the full Library / Folder / Subfolder path. Until a manager is picked, the panel body reads Choose a reference manager above.
A search box, with the placeholder Search references…. Filtering runs inside Typeward over the cached export, and matches citation key, title, authors, and year. Typeward caps results at 200 per query. Matches past that are not listed and nothing on screen marks the cut, so narrow the search to reach them.
A refresh button in the panel header, and an Add from DOI button at the bottom of the panel.

Each result row shows the citation key, the year, the title, and up to three authors. Selecting a row inserts the citation at the cursor, in the syntax of the project format:

Project format	Inserted text
LaTeX	`\cite{key}`
Typst	`@key`

The panel remembers which manager you picked per project, and which library you last browsed per manager. Those are browsing preferences only. library.bib always aggregates every configured source’s full catalog, not only the folder you are browsing.

When nothing is set up, the panel reads No reference providers configured. and points you to Connect Zotero or Mendeley in Settings → Integrations to start.

Citations in your document

Typeward writes the library, and you point your document at it the way you would at any other .bib file:

% biblatex
\addbibresource{.typeward/citations/library.bib}

% classic BibTeX
\bibliography{.typeward/citations/library}

#bibliography(".typeward/citations/library.bib")

The bundled engine deliberately does not skip .typeward when it gathers project files, so library.bib resolves during a compile. With System TeX, the bibliography pass in the built-in recipes is best-effort. When biber or bibtex is not installed, the build log notes the failed tool and the PDF is still produced, with citations unresolved. See Choosing a compile engine for which engine you are on.

Citation autocomplete

In LaTeX projects, Typeward’s own project index serves \cite completion, rather than a language server. The index scans the .tex and .bib files in the project tree and offers their keys, which is why completion works with no language server installed. See Labels, references, and navigation.

That index skips the .typeward folder. Keys that exist only in the generated library.bib are missing from \cite completion, and Ctrl+click (Cmd+click on macOS) does not jump to them. Insert those keys from the Refs tab instead. They resolve normally when the document compiles.

In Typst projects, completion comes from the tinymist language server, and Typeward adds no citation completion source of its own.

Library refreshes

Refreshes are explicit. Typeward rewrites library.bib when:

You select the refresh button in the panel header, which also clears the cached exports and re-probes each source.
You run Refresh reference library from the command palette, Ctrl+K (Cmd+K on macOS), in the References group. On success the toast reads Reference library refreshed with the number of citations.
A DOI or arXiv lookup succeeds.
You change which sources are configured while a project is open.

Nothing refreshes when a project opens, and nothing refreshes on a timer. Typeward caches exports, library lists, and per-folder entries for 60 seconds, so browsing does not re-query the manager on every click. The folder list is never cached, so the tree always mirrors what the manager holds right now.

The write is content-addressed. When a refresh produces byte-identical output, Typeward leaves the file alone, so an unchanged library does not make language servers reparse it.

A refresh never fails as a whole. Each source exports on its own, so Typeward skips a failing source and still writes whatever succeeded. A notification reads N reference sources failed with one line per source. When the refresh itself fails outright, the message is Couldn’t refresh references.

If the panel cannot reach the manager, it says so directly: Couldn’t load references. Check that the reference manager is running, then Refresh. See Troubleshooting for more recovery steps.

Known limitations

library.bib never travels with the project, because .typeward/ stays out of git commits, cloud sync, project exports, and custom templates. On another machine, configure the same reference sources and refresh before compiling.
Entries fetched by DOI or arXiv lookup live in local.bib in the same folder, so they do not travel either. Re-run those lookups on the new machine.
A refresh rewrites library.bib from the sources that answered, so refreshing while Zotero is closed drops the Zotero entries. The last aggregate stays on disk and keeps compiling until you refresh.