Citations and CrossRef

Two features that are unique to Zettlr is its native support for both academic references and cross-referencing of tables, figures, and equations across your documents.

In this section, we describe both types of syntax and explain how Zettlr aids you in adding citations and references. We start with citations, and then explain CrossRef.

Citations

Citations are at the heart of every academic document. Zettlr offers first-class features for supporting your claims with references.

Anatomy of a Citation

Every citation consists of up to four parts, only one of which is mandatory:

• An optional prefix that precedes the citation.
• A required citekey that specifies the piece of work that shall be cited.
• An optional locator that specifies the exact location within the work cited (e.g., a page number or a chapter).
• An optional suffix that includes further information after the reference.

These are the same four parts you can configure in the Zotero picker that you may already be familiar with. Thus, let us start by demonstrating how the settings in the Zotero picker are turned into valid citations when you export a work:

In this example, we have highlighted the prefix in yellow, the actual citation key in green, the locator in purple, and the suffix in teal. You can easily identify that the citation key, which hides behind the “Ermakoff, 2013” label, is mandatory.

The syntax for composing a citation using Pandoc syntax is almost the same as what it will look like when rendered. The example text from above would be written like this:

This is some text [see @Ermakoff2013, p. 45ff for a discussion].

As you can see, the citation syntax exactly mirrors how regular in-text citations are written. The benefit? Zettlr and Pandoc are smart enough to take these pieces of information and format them regardless of which citation style you use!

Types of Citations

Depending on where you want to reference a work, you can choose between three variants of citations:

1. [@Author2015, p. 123] will render as (Author 2015, 123)
2. @Author2015 will render as Author (2015)
3. @Author2015 [p. 123] will render as Author (2015, 123)

The first option will produce a self-contained reference, where prefix, suffix, and all parts of the referenced work are contained within the citation. By using this option, you retain the most flexibility, and upon exporting, it will be converted into the correct syntax (including footnotes, if you use a citation style that mandates footnotes).

However, sometimes you may wish to include a citation seamlessly into your sentence. For example, you may want to write something like this:

… and as Ermakoff (2013, p. 45ff) has pointed out …

This won’t work with option one, as it will place the author’s surname into the brackets instead of in front of them. To ensure that the author name is placed in front of the brackets, and is thus part of the sentence, place the citekey without brackets inside your sentence:

… and as @Ermakoff2013 has pointed out …

This will immediately render as Ermakoff (2013). If you use a citation style that mandates footnotes, the author’s surname will remain a part of the sentence, but the contents of the brackets will be moved into a footnote upon export.

To add additional information to the citation, such as a locator, or a suffix, use square brackets directly after the citekey:

… and as @Ermakoff2013 [p. 45ff] has pointed out …

This will add the locator and/or suffix information into the brackets behind the author’s surname (or in the footnote, depending on the style).

Inserting Citations

Provided you have pointed Zettlr to a file that contains your citations, you can insert citations easily with the help of autocompletion. Start by typing an @-symbol in a valid position. A “valid position” means: the @ is at the beginning of a line, preceded by whitespace, or directly after an opening square bracket.

In this case, Zettlr will automatically suggest citekeys from your library to autocomplete to. Simply start typing letters from the citation key (i.e., of the author name or the year) to have Zettlr remove non-matching citation keys until the key you need is visible. Then, navigate with the arrow keys through the list until the correct entry is highlighted, and press Enter.

Zettlr shows you the bibliographic information of the currently selected citekey in an additional tooltip next to the entry. This helps you verify that you have the correct entry, especially in instances (as you can see in the screenshot) where you have multiple publications per year.

One the autocomplete completes the citekey, it will use your preferred syntax to insert the citation. This includes inserting a closing square bracket, if necessary, or adding square brackets behind the citekey, depending on your setting.

You can change how Zettlr autocompletes citekeys by navigating into the preferences → “Citations” section. Here you can choose one of the three types of citations that have been introduced above. This is helpful especially if you usually use in-text references.

For more information on how to use citations in line with Pandoc's citeproc engine, please refer to the official guide.

CrossRef

With an understanding of citation syntax in mind, it is now time to learn how to write cross-references. As mentioned above, cross-reference syntax is a simple extension of the citation syntax you just learned.

Introduction to CrossRef Syntax

The CrossRef syntax is easy to learn once you understand the citation syntax, since CrossRef is essentially an extension to it. Each cross-reference consists of two elements:

1. A figure/table/equation ID that you specify using Pandoc attributes.
2. A reference that looks almost like a regular citation.

The main difference between a citation and a cross-reference is that the “citekey” of a cross-reference is the ID you specified earlier, and not a work from your reference library. Also, cross-references do not support locators or suffixes.

CrossRef Identifiers

Because cross-references use the same syntax as regular citations, they must follow a specific format so that the CrossRef filter can identify them, and leave actual citations as they are, so that citeproc can handle them.

Each identifier must follow this format:

{fig,tbl,eq,sec,lst}:<a-z0-9->

As you can see, cross-reference identifiers consist of two parts, separated by a colon (:). The first part must be one of fig (for figures), tbl (for tables), eq (for equations), sec (for sections), or lst (for listings such as code blocks). The second part should be a simple label that can include ASCII letters, numbers, dots, and hyphens.

Pandoc CrossRef uses this convention to identify cross-references that it should handle, and distinguish these from citekeys (which, for example, cannot contain colon characters).

Declaring Elements to Cross-Reference

To be able to cross-reference a table, figure, equation, listing, or section, you first must assign it an ID that follows the abovementioned format. You do so by utilizing the Pandoc attribute syntax:

First, an image:

![Image ALT](my-plot.png){#fig:plotA}

Next, a table (where the ID is defined in the caption):

| Column | Column |
|--------|--------|
|   One  |   Two  |

: Table A {#tbl:tableA}

Lastly, an equation:

[$$\hat{y} = \beta_0 + \beta_1 x + \epsilon$$]{#eq:equation1}

The equation in this example is wrapped inside a Pandoc span, which specifies the range of text that this ID should apply to. The image and table are referenced implicitly.

To reference these elements in your text, you use these IDs as if they were citekeys:

As shown in [table @tbl:tableA], we can see […]

See [figure @fig:plotA] for a plot of the regression analysis.

As the plot below shows ([@fig:plotA]), […]

CrossRef Prefixes

Cross-references support prefixes. If you only provide the cross-reference ID, CrossRef will use default labels such as Fig. or Tbl.. By adding a prefix in front of the ID, you can customize this:

As shown above ([see table @tbl.table2.2]), […].

This would render as follows:

As shown above (see table 3), […].

where the contents in the bracket are linked to the actual table (or other referenced element).

You can also reference multiple figures, tables, or other elements at the same time by separating them just like regular citations with semicolons. CrossRef will, upon exporting your file, try to compress all referenced items to compact number ranges (where, say, [@fig:fig1; @fig:fig2; @fig:fig3] would become Figs. 1-3).