Citations and Annotations

Citations and annotations are markers written in the Markdown text. This page describes the complete syntax. The Insert > Citation dialog normally writes them for you, so you rarely need to type them by hand.

Basic syntax#

The full form of a citation is:

[@<flag><form><id>::prefix;;suffix##locator-type&&locator@]

The simplest citation contains only the reference ID: [@smith2020@]. A reference ID is the unique identifier of a reference in the library; it starts with a letter or a digit and may contain letters, digits, dots, underscores and hyphens.

Adjacent citations form a cluster that is laid out as one group: [@smith2020@][@lee2019@]. Do not put spaces between the markers of a cluster.

[[@…]] is an Obsidian wiki link and ![[@…]] an embed. They are not citations and CiteDesk leaves them alone.

The three forms#

! and - are mutually exclusive; write at most one. If the chosen style has no narrative form, a short explanation is shown in its place instead of the citation text.

Locators#

A locator says which part of the work is cited, for example a page, chapter or section. It has two parts that must be written together:

• after ## comes the locator type, one of the CSL type names such as page, chapter, section or paragraph;
• after && comes the locator itself, such as 12-15.

For example [@smith2020##page&&12-15@]. You cannot put the type inside the locator, and you cannot write only one of the two.

In the citation dialog you can type page numbers and other locators straight into the main field, and the dialog writes them in this form for you.

Prefix and suffix#

• After :: comes the prefix and after ;; the suffix. Both are literal text and are placed into the citation exactly as written.
• Even if a suffix contains a page number it is never treated as a locator; use ## and && for a locator.

The standard order is prefix, suffix, locator type, locator. When parsing, the segments may appear in any order, but each may appear only once. For example:

[@smith2020::see;;and chapter 3##page&&12@]

Prefix, suffix and locator must not contain the delimiters (::, ;;, ##, &&) or the start or end of a marker; otherwise the marker would be read wrongly, and the edit dialog warns you under the field.

Keeping the written order#

By default the style decides the order of the references inside a cluster. To keep them in the order you wrote them, add = at the start of any marker of the cluster, for example [@=smith2020@][@lee2019@]. = can be combined with ! or - in either order: [@=-smith2020@]. In the citation dialog, a cluster with more than one reference offers a "Keep written order" option that adds or removes = on every marker of the cluster for you.

Dragging from the library#

Drag reference rows from the library's reference list, or reference cards from the writing sidebar, into the text. The citation markers of those references are written where you drop them; several references dragged at once are joined into one cluster, for example [@smith2020@][@lee2019@]. The insertion is one editing step, like Insert > Citation, and one undo reverses it. A drop inside a code block, or inside another citation or annotation marker, is refused with a message.

A note row dragged into the text is converted to Markdown as a whole: the citations in the note become citation markers, and embedded images are saved in the workspace (see Default location for new attachments in Settings). When references and notes are dragged together, the markers are written first and the notes follow, each as its own editing step. For attachment rows see Pasting and dropping images and files.

Zotero writes a reference dragged into a text editor as formatted citation text. A CiteDesk Markdown document stores only markers, never formatted results, so what is written is the marker, and the style decides how it is formatted.

Annotations#

An annotation is a side note in the text:

[@?@]The text of the note, which may itself contain a citation [@smith2020@].[@/?@]

With a footnote style, every annotation and every top-level citation cluster takes one footnote, numbered in the order they appear; a citation embedded in an annotation is placed in that annotation's footnote and takes no number of its own. With an in-text style, annotations are still laid out as footnotes. Use the Insert Annotation button on the citations page of the right pane to write one.

CiteDesk's footnotes come only from citations and annotations. CiteDesk does not handle Markdown's native footnotes ([^…], ^[…] and footnote definitions): they take no footnote number and are not typeset. The footnotes CiteDesk writes into an exported manuscript use identifiers such as [^citedesk-1].

Typing markers by hand#

Typing a marker by hand can corrupt a document, so the Markdown editor intercepts some inputs: if a typed character would join its neighbours into [^, ^[ or [@, the character does not enter the document; instead you get a notice and the Add/Edit Citation dialog opens. When you confirm, the dialog replaces the characters involved with a correct marker.

Not intercepted: characters in code blocks and other verbatim regions, characters escaped with a backslash, and wiki links and embeds such as [[@. A pasted or dropped [^ or ^[ cannot be stopped and only produces a warning; a pasted [@…@] is treated as a citation copied from elsewhere and accepted as usual.

Regions that are not recognized#

A [@…@] in the following places is not a citation and is not added to the bibliography: fenced and indented code, inline code, math, HTML blocks and inline HTML tags, <…> autolinks, %%…%% and <!--…--> comments, and other structures that Obsidian's parser outputs verbatim. The live preview uses the same judgment, so a place that looks like code does not take effect.

See also: Document Preferences explains how to choose a style, and Exporting a Manuscript explains how markers become a manuscript.