Insert citations
Insert Markdown citations while typing or from the command palette, as the main citation or the alternate citation.
Use the Citation Suggester or command palette to insert a Markdown citation from your Zotero library.
Both entry points search every library in your library scope at once, in one relevance order. While more than one library can contribute results, each suggestion names the library its item comes from. With one library in scope, that label is left off.
Before you enter a search, both lists place papers already cited in the current note first. Each group is ordered by Last Activity, newest first. This is the same order as Recent in the Library View.
When you type a search, both lists rank all results by relevance.
A paper the current note already cites shows the Cited in this note label, with or without a search.
Citation insertion works independently of the Document Citation Set and In-text Citation Rendering. You can insert citations with both source settings off and with Show formatted citations off.
Give your items citation keys
A citation names a Zotero item by its citation key, such as smith2024. ZotLit reads each item's key from Zotero's native citation key field. Better BibTeX writes the keys it generates into that field, so ZotLit sees them as well. In a group library you cannot edit, Better BibTeX keeps its keys to itself, and ZotLit sees only the keys already in the field.
Better BibTeX, a Zotero add-on, is recommended once you start citing. It generates stable citation keys from a pattern for every item, and it can keep a bibliography file up to date with automatic exports for native Pandoc export. ZotLit does not require it.
Insert while typing
The citation suggester opens when you type [@ (or 【@) in the editor. A dropdown appears with items from your Zotero library.
With the opt-in @ trigger enabled, a bare @ at a word boundary (start of line, after a space, or after an opening bracket or quote) also opens the suggester.
Start a citation
Type [@ in the editor. A suggestion list appears.
With @ trigger enabled, typing @ at a word boundary does the same thing. A mid-word @ (e.g. in an email address) is ignored.
Search and select
Continue typing to filter the list. Select an item and press Enter to insert the citation. The citation is inserted with a trailing space so you can keep typing immediately.
Enter asks for the main citation, which the built-in citation text renders as [@citationKey].
An @ query ends at the first space. Type _ where the search needs a space: @machine_learning finds "machine learning". Bracket trigger queries ([@) accept real spaces.
Insert the alternate citation (optional)
To ask for the alternate citation instead, which the built-in citation text renders as @citationKey, do one of:
- End your query with
/before pressingEnter. - Press
Shift+Enteron the selected item.
The instruction row in the suggester shows these shortcuts as a reminder.
If the selected item has no citation key, nothing is inserted and a notice appears: "Selected item has no citation key: {key}."
Suggester settings
- Citation suggester (default: on): enables or disables the inline suggester. Find it in Settings > ZotLit > Citations.
- @ trigger (default: off): also
opens the suggester on a bare
@at a word boundary. Visible only while Citation suggester is on. Find it in Settings > ZotLit > Citations. - Show citation key in suggestions (default: off): shows each item's citation key beside its title in the suggester list. Find it in Settings > ZotLit > Citations.
Insert from the command palette
Open the citation picker
Open the command palette (Ctrl+P on Windows/Linux, Cmd+P on macOS) and run:
A picker appears with your Zotero library.
Select an item
Search for an item and press Enter to insert the main citation.
Press Shift+Enter to insert the alternate citation instead. The modal has no trailing-/ shortcut; Shift+Enter is the only way to ask for the alternate citation here.
Cite with a Literature Note link
Use this form when the citation must also remain an Obsidian link to its Literature Note.
Enable the citation source
Open Settings > ZotLit > Citations and turn on Wikilink citations.
Insert an unaliased Literature Note link
In the citing note, type [[ and select the Literature Note for the item. Keep the link unaliased.
For example:
This finding follows the earlier analysis [[Doe 2020]].Add citation details when needed
Add a Citation Fragment to the link target. This example adds page locator 33:
This finding follows the earlier analysis [[Doe 2020#cite:locator=33]].Replace Doe 2020 with the exact target of your Literature Note.
The link must resolve to a ZotLit Literature Note. Aliases, embeds, heading fragments, block fragments, unresolved targets, and malformed Citation Fragments stay outside the Document Citation Set.
A link such as [[@doe2024]] does not name a Literature Note unless a note
with that exact name is the Literature Note for the item. Use [@doe2024] for
a literal citation key.
When a citation key matches several items
A citation key can belong to more than one Zotero item, whether the twins sit in one library or in two libraries you have in scope. Inserted text carries the key alone, so it would no longer name the item you picked.
ZotLit therefore refuses the insert, from either entry point, and shows: "Citation key @{key} matches multiple Zotero items. Change it in Zotero before inserting a citation." Give one of the items a distinct citation key in Zotero, or narrow your library scope to the library you meant, then insert again.
Keys already written in your notes stay readable. See How in-text citation rendering and navigation work for what such a key does in the editor, the citation popover, and the References Sidebar.
What each gesture inserts
One template document, the citation text, renders every citation you insert. It receives zt.variant, the string main or alt, and decides what each one renders.
maincomes fromEnterin the suggester or in the command palette picker.altcomes fromShift+Enterin either, or from a trailing/in the suggester query. The trailing/wins withoutShift, and the/is stripped from the search.
The built-in citation text renders these:
| What you cite | Main | Alternate |
|---|---|---|
One key smith2024 | [@smith2024] | @smith2024 |
| Two keys | [@a2020; @b2021] | The first item in text, the rest in brackets |
A locator of 62 | [@smith2024, {p. 62}] | @smith2024 [{p. 62}] |
| An item with a suppressed author | [-@smith2024] | [-@smith2024] |
| An item with a prefix | [see @smith2024] | A bracketed cluster, the fallback |
The alternate branch asks Pandoc to prefer the author in text. Where that is not possible (a prefix, or a suppressed author), Pandoc falls back to a bracketed cluster, so the two variants can render the same text. An item with no citation key is dropped from the output.
The rendered citation is normalized to a single line: leading and trailing whitespace is trimmed, and any whitespace run containing a line break collapses to one space. Each insert ends with a trailing space and places the cursor after it; if a space already follows the insert position, it is reused rather than doubled.
To change any of this, edit the Citation text document. See Customize the citation text, or run ZotLit: Customize citation text. The fields your template can read are in Citation templates.
With Pandoc citations and Show formatted citations on, both variants can show formatted text in Live Preview and reading view. Formatting requires the Pandoc engine and selected style.
With Pandoc citations and Open citations as links on, you can open the cited Literature Note. Use a click in Live Preview or Ctrl-click or Cmd-click in Source mode. See How in-text citation rendering and navigation work.
See also
Last updated on