diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 712af49..a946c31 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -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}`. ``` +