# References and citations¶

Because jupyter-book is built on top of Sphinx, there are many ways of referencing content, including use of the excellent sphinxcontrib-bibtex extension to include citations and a bibliography with your book.

Tip

jupyter-book build -W -n --keep-going docs/


This will check for missing references (-n), turning them into errors (-W), but will still attempt to run the full build (--keep-going), so that you can see all errors in one run.

## Cross-references and labels¶

Labels are a way to add tags to parts of your content that you can reference later on. This is helpful if you want to quickly insert links to other parts of your book. Labels can be added before major elements of a page, such as titles or figures.

To add a label, use the following pattern before the element you wish to label:

(my-label)=
# The thing to label


For example, we’ve added the following label above the header for this section:

(content:references)=
## Cross-references and labels


You can insert cross-references to labels in your content with the following syntax: {ref}label-text. For example, the following syntax: {ref}content:references results in a link to this section like so: Cross-references and labels.

There are a few ways to reference your book’s content, depending on what kind of content you’d like to reference. Here is a quick overview of some common options:

• {ref} is used to reference section labels that you define or figures with a name value

• {numref} is used to provide numbered references to figures

• {doc} is used to reference other files in your book

• {eq} is used to reference equations that have been given a label value

Tip

You can reference a section label through {ref}label  or {ref}some text <label> . Documents can be referenced through {doc}path/to/document  or {doc}some text <path/to/document>

If you wish to use Markdown style syntax, then MyST-Markdown will try to find a reference, from any of the above reference types (and more!). This actually has an advantage, in that you can used nested syntax, ror example:

[A **_reference_** to a page](./myst.md)



A reference to a page

Leaving the title empty, will mean the reference uses the target as text, for example the title of a section:

[](./myst.md)


MyST Markdown Overview

Tip

You can control how MyST-Markdown distinguishes between internal references and external URLs in your _config.yml. For example:

parse:
myst_url_schemes: [mailto, http, https]


Means that [Jupyter Book](https://jupyterbook.org) will be recognised as a URL, but [Citations](content:citations) will not:

## Citations and bibliographies¶

You can add citations and bibliographies using references that are stored in a bibtex file that is in your book’s folder. You can then add a citation in-line in your markdown with the {cite} role, and add a bibliography from your bibtex file with the {bibliography} directive.

1. Create a references bibtex file.

touch references.bib

2. Add references. Add some references to your BibTex file. See the BibTex documentation for information about the BibTex reference style. Here’s an example citation:

@article{perez2011python
,	title	= {Python: an ecosystem for scientific computing}
,	author	= {Perez, Fernando and Granger, Brian E and Hunter, John D}
,	journal	= {Computing in Science \\& Engineering}
,	volume	= {13}
,	number	= {2}
,	pages	= {13--21}
,	year	= {2011}
,	publisher	= {AIP Publishing}
}


{cite}mybibtexcitation


For example, this text

{cite}perez2011python


generates this citation: [PGH11]

You can also include multiple citations in one go, like so:

{cite}perez2011python,holdgraf_rapid_2016,RePEc:the:publsh:1367,caporaso2010qiime


becomes [PGH11][HdHP+16][SK14][CKS+10].

4. Add a bibliography. Use the following directive to do so:

{bibliography} path/to/references.bib



This will generate a bibliography for your entire bibtex file. See the bibliography at the end of this page for an example.

When your book is built, the bibliography and citations will now be included.

Warning

If you are adding a bibliography to a different page from your references, then you may need to ensure that page is processed last, which Sphinx does alphabetically. For example, name the file zreferences.rst.

See this sphinxcontrib-bibtex section for more information.

This feature uses sphinxcontrib-bibtex under the hood, see its documentation for more information on how to use and configure bibliographies in your book. Though note the documentation is written for rST and you’ll need to adapt the directive/role syntax for your markdown content.

You can also optionally customize the style of your references. By default, references are displayed in the alpha style. Other currently supported styles include plain, unsrt, and unsrtalpha. These styles create the following bibliography formatting:

• alpha: Use alphanumeric reference labels, citations are sorted by author, year.

• plain: Use numeric reference labels, citations are sorted by author, year.

• unsrt: Use numeric reference labels, citations are sorted by order of appearance.

• unsrtalpha: Use alphanumeric reference labels, citations are sorted by order of appearance.

To set your reference style, use the style option:

{bibliography} path/to/references.bib
:style: unsrt



### Local Bibliographies¶

You may wish to include a bibliography listing at the end of each document rather than having a single bibliography contained in a separate document. Having multiple bibliography directives, however, can cause sphinx to issue duplicate citation warnings.

A common fix is to add a filter to the bibliography directives:

{bibliography} path/to/references.bib
:filter: docname in docnames



See sphinxcontrib-bibtex documentation for local bibliographies

## Bibliography¶

CKS+10

J Gregory Caporaso, Justin Kuczynski, Jesse Stombaugh, Kyle Bittinger, Frederic D Bushman, Elizabeth K Costello, Noah Fierer, Antonio Gonzalez Pena, Julia K Goodrich, Jeffrey I Gordon, and others. Qiime allows analysis of high-throughput community sequencing data. Nature methods, 7(5):335–336, 2010.

HdHP+16

Christopher Ramsay Holdgraf, Wendy de Heer, Brian N. Pasley, Jochem W. Rieger, Nathan Crone, Jack J. Lin, Robert T. Knight, and Frédéric E. Theunissen. Rapid tuning shifts in human auditory cortex enhance speech intelligibility. Nature Communications, 7(May):13654, 2016. URL: http://www.nature.com/doifinder/10.1038/ncomms13654, doi:10.1038/ncomms13654.

PGH11(1,2)

Fernando Perez, Brian E Granger, and John D Hunter. Python: an ecosystem for scientific computing. Computing in Science \& Engineering, 13(2):13–21, 2011.

SK14

John Stachurski and Takashi Kamihigashi. Stochastic stability in monotone economies. Theoretical Economics, 2014.