template/book/syntax_exercises/013.md

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.

::::::{topic} Exercise objective Can you cite references using different in-line styles and customise the way your bibliography appears? ::::::

Citing references properly gives credit to original authors and improves your writing. See the [JupyterBook guide on citations](https://jupyterbook.org/en/stable/content/citations.html) 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}
}

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

You can generate BibTeX entries using free tools like [ZoteroBib](https://zbib.org). Paste a source URL or title, click **Cite**, and export as **BibTeX** to copy into `references.bib`.

Citing sources using {cite}

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

{cite:p}`jason_moore`

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

:class: hint

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]

> You can experiment with different reference styles in your `_config.yml` file to change how these look.

Displaying the bibliography

5. To show the list of cited references at the end of the page, use the {bibliography} directive:

```{bibliography}
```

:class: note

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:

````md
```{bibliography}
:filter: docname in docnames
```

````

This ensures only local references are shown, and avoids build-time warnings.

Customising citation styles

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

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

• author_year
• label
• super
• number

:class: hint

Heres's how each style will appear for the example in the shared bibliography:

- `author_year` → Moore (2023)
- `label` → [jason_moore]
- `super` → ¹
- `number` → [1]

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

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

• alpha
• plain
• unsrt
• unsrtalpha

:class: hint

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

:class: note

- **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).

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

11. Add a commit message.

12. To see your changes, go to {octicon}play 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).

13. Do you see your change? If you don't see it click CTRL+F5/Control+F5to refresh the page.

:class: note

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