# 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?
::::::

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

```{tip}
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:

```md
{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}`

```{admonition} What to expect when you render these
:class: hint, dropdown
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

5. 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](../references.md):

````md
```{bibliography}
```
````

`````{admonition} Avoiding duplicate citation warnings
:class: warning

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.

```yaml
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`

```{admonition} What each reference style will look like
:class: hint, dropdown
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](https://teachbooks.io/manual/features/apa.html)

```

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.

````md
```{bibliography}
:style: unsrt
```

````

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

- `alpha`
- `plain`
- `unsrt`
- `unsrtalpha`

```{admonition} What each bibliography style looks like
:class: hint, dropdown
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

```


```{admonition} Bibliography style vs. Reference style
: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`+`F5`to refresh the page.


```{admonition} Check your understanding
: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}`.
```