Citations and Bibliography

Citations automatically show up in your site, including a references section at the bottom of the page. These citations are able to be clicked on to see more information, like the abstract. There are two different ways to add citations to your documents:

1. Add a Markdown link to a DOI; and

2. Add a BibTeX file, which can be exported from any reference manager, and adding a cite role to your content.

Simple Referencing with a DOI Link¶

Link to any DOI in your Markdown files or Jupyter Notebooks by including a link to the DOI. This will be transformed to a citation with a pop-up panel on hover like this: Cockett, 2022, and the reference information will be added to the reference section at the bottom of the page. Here’s some example syntax:

This is a link in Markdown: [Cockett, 2022](https://doi.org/10.5281/zenodo.6476040).

To automatically insert the citation text, provide a standalone DOI link without link text:

• [](doi:10.5281/zenodo.6476040)

• <doi:10.5281/zenodo.6476040>

For example: Cockett (2022).

If the BibTeX file in your project has this DOI, that citation will be used.

If the BibTex file does not have this DOI, the citation data will be downloaded from https://doi.org (and cached to a local file in the _build directory).

Clear the DOI cache with : myst clean --cache.

To modify the style of the inserted citation text: Use the styles in Table 1 (this works with or without a BibTeX file)

Numbered Citations¶

The default citations are narrative, for numbered citations, these can be set in the site.options.numbered_references in your myst.yml (See Site Options).

site:
  options:
    numbered_references: true

Writing DOIs to BibTeX¶

If you encounter problems fetching DOIs from https://doi.org, for example the downloaded citation does not include all the data you expect or requests to https://doi.org are failing on an automated continuous integration platform, you may write your DOI citations to file using the MyST command:

myst build --doi-bib

This will generate a BibTeX file myst.doi.bib which you may then rename, edit, and save to your project. On subsequent builds, the DOIs will be loaded from this file rather than fetched remotely.

Including BibTeX¶

A standard way of including references for $\LaTeX$ is using BibTeX, you can include a *.bib file or files in the same directory as your content directory for the project. These will provide the reference keys for that project.

If you want to explicitly reference which BibTeX files to use, as well as what order to resolve them in, you can use the bibliography field in your frontmatter, which is a string array of local or remote files. This will load the files in order specified.

bibliography:
  - my_references.bib
  - https://example.com/my/remote/bibtex.bib

The remote BibTeX can be helpful for working with reference managers that support remote links to your references.

Markdown Citations¶

You can add citations to any BibTeX entry using the citation key preceded by an @, for example, @author2023. This syntax follows the pandoc citation syntax. Multiple citations can be grouped together with square brackets, separated with semi-colons. It is also possible to add a prefix or suffix to parenthetical citations, for example, [e.g. @author2023, chap. 3; @author1995]. To add a suffix to a narrative citation, follow the citation with the suffix in square brackets, for example, @author2023 [chap. 3]. As with a link to a DOI, you can also use the DOI directly instead of the BibTeX key.

Citation Roles¶

MyST also provides a number of roles for compatibility with Sphinx and Jupyter Book V1. To create a citation role in Markdown, use either a parenthetical or textual citation:

This is a parenthetical citation {cite:p}`cockett2015`.
You can also use a narrative citation with {cite:t}`cockett2015`.
You can also use a narrative citation with {cite:p}`cockett2015; heagy2017`.
You can also add prefix and suffix {cite:p}`{see}cockett2015{fig 1}`.

This is the difference between: Cockett et al., 2015 and Cockett et al. (2015). You can have many citation keys in a single role, by separating them with a semicolon, ;, for example: Cockett et al., 2015Heagy et al., 2017. Including a prefix or suffix is displayed as see Cockett et al., 2015, fig 1.

You can also include DOIs in citations (cite, cite:t, and cite:p) which will be linked in the same way as a simple Markdown link, but will match the reference style of the project.

This will be a citation: {cite}`10.1093/nar/22.22.4673`.

This will show as: Thompson et al. (1994).