Cross-references and citations with Quarto

1 Cross-references

Cross-referencing allows you to refer to sections, figures, tables, and code blocks within your document. This is essential for academic writing. To cross-reference content in your document, you need to give it a label first, which will be used for referencing.

2 Sections

For sections, you can label a particular section using the {#sec-yourlabel} syntax. For example, in this h2 heading for the results section:

## Results {#sec-results}

Then, to reference it elsewhere in your text, use @sec-yourlabel, like this:

As shown in @sec-results, ...

2.1 Tables and figures

Tables and figures are among the most common elements for presenting data and results. For them, you will use tbl- and fig- instead of sec-.

There are two main methods to cross-reference them. If the table or figure is generated by a code chunk, you can use the label: option in your chunk to identify them. For example, the table produced by the code below will be referenced with @tbl-planets.

```{python}
#| label: tbl-planets
#| tbl-cap: Astronomical object

from IPython.display import Markdown
from tabulate import tabulate
table = [["Sun","696,000",1.989e30],
         ["Earth","6,371",5.972e24],
         ["Moon","1,737",7.34e22],
         ["Mars","3,390",6.39e23]]
Markdown(tabulate(
  table, 
  headers=["Astronomical object","R (km)", "mass (kg)"]
))
```

The other case is when tables and figures are created directly using Markdown. You will have to include a similar tag as for the sections, in this case {#tbl-mylabel}. Then, in your text you can use the same method to reference them: @tbl-letters.

| Name  | Value |
|-------|-------|
| A     | 10    |
| B     | 20    |

: Caption {#tbl-letters}

Or in the case of a figure:

![An Elephant](elephant.png){#fig-elephant}
Tip

To add captions to your code-generated tables and figures, use fig-cap or tbl-cap in the chunk headers.

3 Citations

Citations to reference external sources such as journal articles, books, or websites can also be used in Quarto. They can be added manually, but we recommend integrating Zotero into your workflow. This integration is already set up for all IDEs in the visual editor.

To activate the visual editor on Positron and VS Code, right-click on your qmd file and select Edit in Visual Mode.

Activate visual mode
Tip

To add captions to your code-generated tables and figures, use fig-cap or tbl-cap in the chunk headers.

It is also important to have a tidy set of citation keys for your references, since you will use those to reference them in your text. The Better BibTeX plug-in can help with that.

To start adding references to your work, if you are in the visual editor, start by typing an @. A menu with a list of possible references will pop up.

Menu with citable sources

You can look for the source manually within that menu, but the most efficient way is to type directly the BibTeX citation key in Zotero.

Citation key in Zotero

After selecting the source, a window will appear where all the details for that citation will appear. You can also choose where to add that citation. This means that the system does collect all the citations that you use in your work, and you do not have to worry about creating a bibliography manually!

Citation window

4 Bibliographies

By default, bibliographies list all cited sources at the end of your document. The bibliography will be rendered automatically based on your citations.

If you want to include it in a different place in your document (not at the end), you can include ::: {#refs} ::: in the location where you want to render the list of references.

One last important element is the format of the references and citations. Different institutions require different styles; you can easily change the style of referencing by including a CSL (Citation Style Language) file to configure Quarto to render citations and references with that particular style. You should include a line similar to this in your YAML file:

csl: mycsl.csl

5 Practical: adding citations and references to your paper

Try the following steps:

  • Add a bibliography file to your project.
  • Cite at least one source in your document.
  • Create a figure and a table, each with a label and caption.
  • Reference your figure and table in the text using cross-references.
  • Render your document and check that citations, references, and cross-references are formatted correctly.

Reuse