Exercise 13: Adding a Bibliography#
In this exercise, you will learn how to cite sources using the shared bibliography provided in this template, and how to control the citation style and reference formatting using {cite}
roles and the {bibliography}
directive.
Tip
Citing references properly gives credit to original authors and improves your writing. See the JupyterBook guide on citations for full details.
Citing sources using {cite}
#
To reference a source in-line, use one of the
{cite}
roles. Try the following:
{cite:p}`jason_moore`
You can also use other variants of
{cite}
depending on the style you want. Try adding the following to your Markdown file and see how the output differs:
{cite:p}
{cite:t}
{cite:ps}
{cite:ts}
Hint: What to expect when you render these
Here’s how the citation will appear for the example in the shared bibliography:
{cite:p}
→ Parenthetical citation
→ [Moore, 2023]{cite:t}
→ Textual citation
→ Moore [2023]{cite:ps}
→ Parenthetical, full authors
→ [Moore, 2023]{cite:ts}
→ Textual, full authors
→ Moore [2023]
Displaying the bibliography#
To show the list of cited references at the end of the page, use the
{bibliography}
directive. In this template, the bibliography is already added to the page:
```{bibliography}
```
Avoiding duplicate citation warnings
If you use {bibliography}
in multiple files, you might see warnings about duplicate citations when building your book. To avoid this, restrict the bibliography to only show references cited in the current page by adding a :filter:
option:
```{bibliography}
:filter: docname in docnames
```
This ensures only local references are shown, and avoids build-time warnings.
Customising citation styles#
You can change the reference style (how citations appear in your text) by editing the
_config.yml
file in your book folder. Add or modify the following section, and see how the referece style changes.
sphinx:
config:
bibtex_reference_style: author_year
Try replacing
author_year
with the following and see how the citation outputs change:
author_year
label
super
number
Hint: What each reference style will look like
Heres’s how each style will appear for the example in the shared bibliography:
author_year
→ Moore (2023)label
→ [jason_moore]super
→ ¹number
→ [1]
Feeling brave? You can also use APA references, although this is not a default option. More information on to set this up is available in the TeachBooks manual
You can also change the bibliography style (how the reference list is formatted) using the
:style:
option in the{bibliography}
directive. Try replacing the style with the following, and see how the bibliography style changes.
```{bibliography}
:style: unsrt
```
Experiment with the following different styles, and see how the bibliography style changes:
alpha
plain
unsrt
unsrtalpha
Hint: What each bibliography style looks like
Heres’s how each style will appear for the example in the shared bibliography:
alpha
→ References labelled as [Knu84], sorted by author/yearplain
→ References numbered [1], sorted by author/yearunsrt
→ Numbered [1], in order of appearance in the textunsrtalpha
→ Alphanumeric like [Knu84], but in order of appearance
Bibliography style vs. Reference style
Reference style controls how citations look in your text (e.g., [1] vs. (Author, Year)).
Bibliography style controls how the reference list is formatted (e.g., sorted, numbered, APA).
When you are ready, commit your changes to the repository by clicking on the green
Commit changes
button.Add a commit message.
To see your changes, go to
Actions
- The most recent workflow runoverview.md / the commit message of the commit you just made
- Wait for it to finish - In the summary, click on the link of your book shown in the tableBranches deployed
and underPrimary book at root
(getting bored of waiting? There’ll be exercising on doing this locally which prevents you from waiting).Do you see your change? If you don’t see it click
CTRL
+F5
/Control
+F5
to refresh the page.
Check your understanding
Before moving on, make sure you understand:
How to add a new reference to the shared
references.bib
file.How to use
{cite}
roles to control in-line citation appearance.How to change the citation style in
_config.yml
.How to display the bibliography with
{bibliography}
.