Get started with references¶

References allow you to refer to other content in your book or to external content. They allow you to automatically generate links to that content, or to add extra information like numbers to the reference.

Citations and bibliographies allow you to cite scholarly work and provide bibliographies that allow readers to follow the references.

This tutorial covers the basics of setting up references as well as citations and bibliographies for your book.

For more information about citation and reference syntax, see the sphinxcontrib-bibtex documentation. Note that this documentation is written with rST syntax in mind and you’ll need to adapt the directive/role syntax for your Markdown content.

Prerequisites¶

This tutorial assumes that you’ve either created a demo Jupyter Book from Create your first book, or that you’ve got your own Jupyter Book to work from.

Basic structure of a reference¶

Cross-references in Jupyter Book usually involve two things:

1. Create a label for something. This is the thing you’ll refer to later in your reference.

2. Create a reference with a target. This target is usually the label you created in #1.

Create a label¶

First, we’ll create a label. Labels must come just before headers. You can then refer to them elsewhere in your text.

(my-label)=

Some text


This is how you specify a label called my-label that points to the header just below (## My header).

Now that you’ve created a label, you can refer to it from elsewhere. Try adding the following markdown on the same page (or some other page).

Here's some text and [here's my label](my-label).


jb build pathto/mybook


You should see that your reference has been replaced with a link to the right spot on the page.

Create a citation¶

Create a bibtex file¶

You’ll need a bibtex file to store the information for your citations. In this case, we’ll create an empty bibtex file and populate it with one reference.

touch references.bib


Next, configure your book to include this bibtex file, like so:

# In _config.yml
bibtex_bibfiles:
- references.bib


This will activate the sphinxcontrib.bibtex extension

Finally, note that the default reference style is label which shows up as an in-line link in the rendered HTML as [ABC21]; it is described in detail here along with other styles. You can adjust the reference style in your book’s _config.yml file like so:

# In _config.yml
sphinx:
config:
bibtex_reference_style: author_year


@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}
}


See the BibTex documentation for information on the BibTex reference style.

Here is my nifty citation {cite}perez2011python.


Re-build your book, and it should look like this:

Here is my nifty citation .

Now try adding multiple citations at once by separating each one with a comma.

Here are multiple citations {cite}perez2011python,holdgraf_rapid_2016,RePEc:the:publsh:1367,caporaso2010qiime!


when you build your book, it should look like this:

Here are multiple citations !

Finally, we’ll generate a bibliography for our citations. Links to this bibliography will automatically be created when you cite something.

We’ll use the {bibliography} directive to add one to our book. Add the following to your page:

{bibliography}



This will generate the bibliography of all citations in your book. See the bibliography below for an example.