How citation key links work

Citation Key Links make bracketed [@key] citations clickable in Obsidian's editor. The feature is off on new installs and remains on when ZotLit migrates earlier settings.

The Citation key links setting controls the feature. It relies on an internal Obsidian editor integration, so Obsidian changes can affect its behavior.

What happens in the editor

When a bracketed citation appears in Live Preview or Source mode, ZotLit reads its citation key. It then checks the frontmatter property selected by Citation key property. This setting defaults to citekey.

Only Literature Notes count as matches. A Markdown file must have a valid zotero-key property before its Citation Key Property value can resolve a link.

When exactly one Literature Note has the matching property value:

• Hover preview uses Obsidian's built-in page preview.
• Click navigation opens that note directly.

Zero or multiple direct matches do not provide hover preview. Clicking still starts Zotero resolution.

What gets recognized

A citation key becomes a link only when it sits inside square brackets. The recognized forms are:

• [@key] (single cite)
• [@key, p. 3] (cite with a locator)
• [@a; @b] (multi-cite; each citation key is its own link)

The brackets matter because Obsidian's editor already displays bracketed text as a link, and that display is what ZotLit's hook builds on. A bare @key outside brackets is ordinary text to the editor. It gets no hover preview and no click navigation, even though Pandoc accepts the bare form as a citation.

How click resolution works

ZotLit first opens an exact, unique property match. Otherwise, it finds the Zotero item by citation key in the Default library.

After finding the item, ZotLit checks the authoritative zotero-key identity again. It opens that Literature Note when one exists. ZotLit creates a note only when no matching zotero-key exists.

For the full step-by-step details, including error messages and library resolution, see Open a note from a citation key.

Citation Key Property and Managed Frontmatter

The default Managed Frontmatter list includes a citekey field backed by zt.citationKey. You can edit, rename, or remove this ordinary managed field.

Set Citation key property to the property that stores citation keys in your Literature Notes. If the selected property is missing from Managed Frontmatter, ZotLit shows a notice. Citation Key Links remain active, and existing unmanaged property values can still resolve notes.

Only a non-empty string value can match a citation key. The zotero-key property remains the system identity for Literature Notes.

Reading mode limitation

The integration applies only to Obsidian's live editor. Reading mode uses a separate rendering path, so citation key spans remain plain text there.

See also