Skip to article content

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) adding a markdown link to a DOI; and (2) by adding a BibTeX file, which can be exported from any reference manager, and adding a cite role to your content.

Link to any DOI in your markdown files or Jupyter Notebooks by including a link to the DOI. Provided the DOI is formatted correctly, this will be transformed during the build process to a citation with a pop-up panel on hover like this: Cockett, 2022, and the reference information will be automatically added to the reference section at the bottom of your notebook (see below👇).

This is a link in markdown: [Cockett, 2022](

It is also possible to to drop the link text, that is:
<doi:10.5281/zenodo.6476040> or [](doi:10.5281/zenodo.6476040),
which will insert the citation text in the correct format (e.g. adding an italic “et al.”, etc.). The citation data for these DOIs will be downloaded from once and cached to a local file in the _build directory. This cache may be cleared with myst clean --cache.

Providing your DOIs as full links has the advantage that on other rendering platforms (e.g. GitHub), your citation will still be shown as a link. If you have many citations, however, this will slow down the build process as the citation information is fetched dynamically.

Including BibTeX

A standard way of including references for LaTeX\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.

  - my_references.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.

Table 1:Examples of Markdown citations

@cockett2015Cockett et al. (2015)Narrative citation
[@cockett2015]Cockett et al., 2015Parenthetical citation
[@cockett2015; @heagy2017]Cockett et al., 2015Heagy et al., 2017Multiple parenthetical citations
[-@cockett2015]2015Show citation year
[e.g. @cockett2015, pg. 22]e.g. Cockett et al., 2015, pg. 22Prefix and suffix
@cockett2015 [pg. 22]Cockett et al. (2015, pg. 22)Suffix for narrative citations
@10.1093/nar/22.22.4673Thompson et al. (1994)Citation using a DOI directly

Citation Roles

MyST also provides a number of roles for compatibility with Sphinx and JupyterBook. 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).

  1. Cockett, R. (2022). Future of Research Communication & Collaboration. 10.5281/ZENODO.6476040
  2. PRIESTLEY, C. H. B., & TAYLOR, R. J. (1972). On the Assessment of Surface Heat Flux and Evaporation Using Large-Scale Parameters. Monthly Weather Review, 100(2), 81–92.<;0081:otaosh>;2
  3. Abduallah, Y., Jordanova, V. K., Liu, H., Li, Q., Wang, J. T. L., & Wang, H. (2022). Predicting Solar Energetic Particles Using SDO/HMI Vector Magnetic Data Products and a Bidirectional LSTM Network. The Astrophysical Journal Supplement Series, 260(1), 16. 10.3847/1538-4365/ac5f56
  4. Cockett, R., Kang, S., Heagy, L. J., Pidlisecky, A., & Oldenburg, D. W. (2015). SimPEG: An open source framework for simulation and gradient based parameter estimation in geophysical applications. Computers & Geosciences, 85, 142–154.
  5. Heagy, L. J., Cockett, R., Kang, S., Rosenkjaer, G. K., & Oldenburg, D. W. (2017). A framework for simulation and inversion in electromagnetics. Computers & Geosciences, 107, 1–19.
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication