mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-12 22:25:52 +00:00
133 lines
4.6 KiB
Markdown
133 lines
4.6 KiB
Markdown
# 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.
|
||
|
||
For example, the following tells Jupyter Book to use `references.bib` for any citations on that page:
|
||
|
||
```yaml
|
||
---
|
||
bibliography: references.bib
|
||
---
|
||
```
|
||
````
|
||
|
||
|
||
|
||
```{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.
|
||
```
|