From d4b45a308eb7f21c2353b09fd39b0e260fdd474f Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 27 Jun 2025 23:04:55 +0200 Subject: [PATCH 1/6] 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. +``` From a7135c51b82c29592f5f3b839a9e3a9181a6a804 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 27 Jun 2025 23:09:43 +0200 Subject: [PATCH 2/6] small changes --- book/syntax_exercises/013.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 5929d6c..8f03cde 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -2,9 +2,9 @@ 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 +::::::{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. @@ -33,7 +33,7 @@ Citing references properly gives credit to original authors and improves your wr 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: +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 --- @@ -63,14 +63,14 @@ You can add this `bibliography:` key in `_config.yml` to make the reference file ## Citing sources in different formats -5. To cite a source in **numeric style** (default when using `unsrt`), use `[@key]`. Try the following example: +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. +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} @@ -86,7 +86,7 @@ Einstein's paper on relativity changed physics [@einstein1905]. @einstein1905 describes special relativity... ``` -8. You can also site **multiple references** by separating them with semicolons: +8. You can also site multiple references by separating them with semicolons: ```md Several foundational works include [@einstein1905; @knuth1984]. From 1721ff9a6246f613e377a9d6bc6dc94cede6a2db Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 27 Jun 2025 23:14:17 +0200 Subject: [PATCH 3/6] small changes 2 --- book/syntax_exercises/013.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 8f03cde..712af49 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -45,14 +45,6 @@ bibliography: references.bib :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 ---- -``` ```` From 487a436c57d638e40fc648fc01281b26c0010b80 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 1 Jul 2025 15:35:43 +0200 Subject: [PATCH 4/6] Update 013.md --- book/syntax_exercises/013.md | 192 ++++++++++++++++++++++------------- 1 file changed, 123 insertions(+), 69 deletions(-) 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}`. ``` + From 46ee078f7e928b4a0315bf29e06fb04e4706a91d Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 1 Jul 2025 15:51:08 +0200 Subject: [PATCH 5/6] small changes --- book/syntax_exercises/013.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index a946c31..a097424 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -62,7 +62,6 @@ Here’s how the citation will appear for the example in the shared bibliography - `{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 @@ -77,7 +76,7 @@ Here’s how the citation will appear for the example in the shared bibliography `````{admonition} Avoiding duplicate citation warnings -:class: note +:class: warning 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: From fc439eca9cf670c18dd4f519b5ed2a93f17a2418 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 2 Jul 2025 07:42:13 +0200 Subject: [PATCH 6/6] Update 013.md --- book/syntax_exercises/013.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index a097424..3cadb1a 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -66,15 +66,13 @@ Here’s how the citation will appear for the example in the shared bibliography ## Displaying the bibliography -5. To show the list of cited references at the end of the page, use the `{bibliography}` directive: +5. To show the list of cited references at the end of the page, use the `{bibliography}` directive. In this template, the bibliography is already added to the [page](../references.md): ````md ```{bibliography} ``` ```` - - `````{admonition} Avoiding duplicate citation warnings :class: warning