Citations and bibliographies#

Warning

If you are using docutils>=0.18,<20 then the page containing the bibliography directive will not have the correct layout. While docutils is patched we recommend using docutils==0.17.1 which can be installed by:

pip install docutils==0.17.1

This is due to this issue

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 include the bibliography from your bibtex file with the {bibliography} directive.

See also

This functionality uses the excellent sphinxcontrib-bibtex extension.

Basic citations#

To get started with citations in Jupyter Book, check out Get started with references.

Change the in-line citation style#

There are a few alternatives roles that you can use to change the in-line citation style. Below are a few examples:

  • The citation {cite:p}`perez2011python` results in [Perez et al., 2011]

  • The citation {cite:t}`perez2011python` results in Perez et al. [2011]

  • The citation {cite:ps}`perez2011python` results in [Perez, Granger, and Hunter, 2011]

  • The citation {cite:ts}`perez2011python` results in Perez, Granger, and Hunter [2011]

See also

For a more complete list of in-line citation styles, check out the sphinxcontrib-bibtex docs.

Select your bibliography style#

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}
:style: unsrt
```

Change the reference style#

To set the reference style, use the bibtex_reference_style field in your book’s _config.yml file.

# In _config.yml
sphinx:
  config:
    bibtex_reference_style: author_year
    bibtex_bibfiles: "your_reference_file.bib"

There are a few options for your in-line citation style such as label, super, and author-year.

See also

For a list of configuration options and more detail about this, see the sphinxcontrib-bibtex docs

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}
:filter: docname in docnames
```

See sphinxcontrib-bibtex documentation on local bibliographies.

Example Bibliography#

An example bibliography, for reference:

[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,3,4)

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.