admin2/template
1
0
Fork 0
mirror of https://github.com/TeachBooks/template.git synced 2026-11-12 22:25:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update 013.md

Browse source
This commit is contained in:
Katia Gatt 2025-07-01 15:35:43 +02:00
parent 1721ff9a62
commit 487a436c57
1 changed files with 123 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

192
book/syntax_exercises/013.md
View file

@ -1,125 +1,179 @@
# 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).
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 include references in your book using a bibliography file and cite them using different formats?
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 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.
````
## 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 add this `bibliography:` key in `_config.yml` to make the reference file available to the whole book instead of just per page.
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 in different formats
## Citing sources using `{cite}`
5. To cite a source in numeric style (default when using `unsrt`), use `[@key]`. Try the following example:
3. To reference a source in-line, use one of the `{cite}` roles. Try the following:
```md
Einstein's paper on relativity changed physics [@einstein1905].
{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:
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.
* `{cite:p}`
* `{cite:t}`
* `{cite:ps}`
* `{cite:ts}`
```{dropdown} Hint: What to expect when you render these
: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:
````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...
`````{admonition} Avoiding duplicate citation warnings
: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
```
8. You can also site multiple references by separating them with semicolons:
````
```md
Several foundational works include [@einstein1905; @knuth1984].
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:
## Rendering the bibliography
* `author_year`
* `label`
* `super`
* `number`
9. At the bottom of the page (or wherever appropriate), include a `{bibliography}` directive to render the list of references:
```{dropdown} Hint: What each reference style will look like
: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.
````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)
9. Experiment with the following different styles, and see how the bibliography style changes:
- `alpha`
- `plain`
- `unsrt`
- `unsrtalpha`
```{dropdown} Hint: What each bibliography style looks like
: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
```
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.
```{admonition} Bibliography style vs. Reference style
:class: note
13. Add a commit message.
- **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).
```
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).
10. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
15. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
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 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.
- 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}`.
```