Adding a Bibliography

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.

Adding an entry to the shared bibliography#

  1. The TeachBooks template already includes a shared bibliography file (references.bib). Locate and open the file. You will see the following example entry:

@misc{jason_moore,
  title={Learn Multibody Dynamics, SymPy},
  author={Moore, Jason},
  howpublished={\url{https://moorepants.github.io/learn-multibody-dynamics/sympy.html}},
  year={2023}
}

  1. Add a new reference of your own. You can use a DOI, book title, or URL.

Tip

You can generate BibTeX entries using free tools like ZoteroBib. Paste a source URL or title, click Cite, and export as BibTeX to copy into references.bib.

Citing sources using {cite}#

  1. To reference a source in-line, use one of the {cite} roles. Try the following:

{cite:p}`jason_moore`

  1. 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}

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#

  1. 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#

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

  1. Try replacing author_year with the following and see how the citation outputs change:

  • author_year

  • label

  • super

  • number

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

  1. 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
```

  1. Experiment with the following different styles, and see how the bibliography style changes:

  • alpha

  • plain

  • unsrt

  • unsrtalpha

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/year

  • plain → References numbered [1], sorted by author/year

  • unsrt → Numbered [1], in order of appearance in the text

  • unsrtalpha → 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).

  1. When you are ready, commit your changes to the repository by clicking on the green Commit changes button.

  2. Add a commit message.

  3. To see your changes, go to Actions - The most recent workflow run overview.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 table Branches deployed and under Primary book at root (getting bored of waiting? There’ll be exercising on doing this locally which prevents you from waiting).

  4. Do you see your change? If you don’t see it click CTRL+F5/Control+F5to 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}.

Contents