# Exercise 13: Adding a Bibliography

In this exercise, you will learn how to add a bibliography to your book and how to include references to sources using different citation styles (e.g., numeric, author–year, or label-based).

::::::{topic} Exercise objective
Can you include references in your book using a bibliography file and cite them using different formats?
::::::

```{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 a bibliography

1. Open or create a Markdown file where you want to use references.

2. Make sure a bibliography file exists in your project. The default format is `.bib`, which uses BibTeX syntax. You can create a file called `references.bib` in the root or relevant folder of your project. 

3. In the `references.bib` file, and add entries to reference like the examples below.

```
@book{knuth1984,
  author    = {Donald E. Knuth},
  title     = {The TeXbook},
  year      = {1984},
  publisher = {Addison-Wesley}
}

@article{einstein1905,
  author  = {Einstein, Albert},
  title   = {On the Electrodynamics of Moving Bodies},
  journal = {Annalen der Physik},
  year    = {1905}
}
```
4. Return to the Markdown file you are working on, and link the bibliography file using a front matter header. This should be placed at the very top of your file to automatically enable citations and bibliography rendering:

```md
---
bibliography: references.bib
---
```

````{admonition} What is a front matter header?
:class: note

A front matter header is a block of configuration settings written in YAML and placed at the very top of a Markdown file, enclosed between triple dashes `---`. It allows you to specify page-level options such as the title, tags, or the bibliography file to use.
````



```{tip}
You can add this `bibliography:` key in `_config.yml` to make the reference file available to the whole book instead of just per page.
```

## Citing sources in different formats

5. To cite a source in numeric style (default when using `unsrt`), use `[@key]`. Try the following example:

```md
Einstein's paper on relativity changed physics [@einstein1905].
```


6. To cite a source in author–year style, change the style to `author-year` as shown below. Try this out and see how the citation from the previous step changes to the new formatting style.

````md
```{bibliography}
:style: author-year
:filter: False
```
````


7. You can also write inline references using `@key`, which will automatically expand to author/year or number depending on the style. Try this out:

```md
@einstein1905 describes special relativity...
```

8. You can also site multiple references by separating them with semicolons:

```md
Several foundational works include [@einstein1905; @knuth1984].
```


## Rendering the bibliography

9. At the bottom of the page (or wherever appropriate), include a `{bibliography}` directive to render the list of references:

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

```{tip}
You can use `:style:` to choose different reference formats. Common options include:
- `unsrt` (numerical, unsorted)
- `plain` (numerical, sorted)
- `author-year` (author/date)
- `apa`, `ieee`, `nature` (other standard citation styles)
```

10. Ensure your `.bib` file is correctly formatted and that each key used in `@key` or `[@key]` matches an entry in that file. If a reference doesn’t show up, double-check the syntax or run the build process again.

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

13. Add a commit message.

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

15. 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 include and link a bibliography file.
- How to cite a reference using `@key` and `[@key]`.
- How to switch between citation styles like numeric or author–year.
- How to render the bibliography list at the bottom of a page.
```