From d4b45a308eb7f21c2353b09fd39b0e260fdd474f Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 27 Jun 2025 23:04:55 +0200 Subject: [PATCH] exercise 13 --- book/_toc.yml | 1 + book/syntax_exercises/013.md | 133 +++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 book/syntax_exercises/013.md diff --git a/book/_toc.yml b/book/_toc.yml index abecdbf..c3263ab 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -25,6 +25,7 @@ parts: - file: syntax_exercises/010.md - file: syntax_exercises/011.md - file: syntax_exercises/012.md + - file: syntax_exercises/013.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md new file mode 100644 index 0000000..5929d6c --- /dev/null +++ b/book/syntax_exercises/013.md @@ -0,0 +1,133 @@ +# 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. +```