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

Merge branch 'main' into manual_description

Browse source
This commit is contained in:
Tom van Woudenberg 2025-04-14 11:24:18 +02:00
commit 64d80b478c
9 changed files with 645 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

51
CITATION.cff Normal file
View file

@ -0,0 +1,51 @@
# This CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to generate yours today!
cff-version: 1.2.0
title: 'TeachBooks Template' # replace with your own book title when you use this template
authors: #replace with your own name(s) if you use this template
- email: info@teachbooks.io
name: 'TeachBooks Development Team'
website: 'https://teachbooks.io/'
message: 'If you use this teachbook, please cite it using these metadata.'
preferred-citation:
type: book
authors: #replace with your own name(s) if you use this template
- email: info@teachbooks.io
name: 'TeachBooks Development Team'
website: 'https://teachbooks.io/'
# - given-names: Tom
# name-particle: van
# family-names: Woudenberg
# email: t.r.van.woudenberg@tudelft.nl
# affiliation: TeachBooks
# orcid: 'https://orcid.org/0000-0002-9536-061X'
url: 'https://teachbooks.github.io/template/' # replace with your own URL (book website / publisher link) when you use this template
identifiers:
- type: url
value: 'https://teachbooks.github.io/template/' # replace with your own URL when you use this template
description: 'Published book on GitHub Pages'
- type: url
value: 'https://github.com/TeachBooks/template' # replace with your own URL when you use this template
description: 'GitHub repository'
abstract: >- # replace with your own abstract when you use this template
The template allows you to start your own TeachBook and
hosting that TeachBook online without knowledge on Git,
the Jupyter book package, python or anaconda. It doesn't
elaborate on the collaborative functionalities of Git or
how to edit the book
keywords: # replace with your own keywords when you use this template
- TeachBooks
- Template
- 'Jupyter Book'
title: 'TeachBooks Template' # replace with your own book title when you use this template
institution:
name: 'TeachBooks' # replace with your own institution when you use this template
license: CC-BY-4.0
license-url: 'https://creativecommons.org/licenses/by/4.0/'
copyright: '© 2025 TeachBooks' # replace with your own affiliation / name when you use this template
languages:
- en # replace with your book language when you use this template
contact: # replace with your own contact information when you use this template
- email: info@teachbooks.io
name: 'TeachBooks Development Team'

4
WAIVER Normal file
View file

@ -0,0 +1,4 @@
Technische Universiteit Delft hereby disclaims all copyright interest in the
program “TeachBooks Template” (a GitHub template repository to ease the
creation of TeachBooks) written by the Author(s).
Stefan Aarninkhof, Dean of Civil Engineering & Geosciences

7
book/_config.yml
View file

@ -7,6 +7,11 @@ execute:
only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents
html:
favicon : "figures/TB_favicon.ico" # Replace this with your own favicon
baseurl : "https://<user/org>.io/<repo>" # Replace this with your own URL
sphinx: # Options passed on to the underlying sphinx-parser
config:
html_js_files:
@ -27,8 +32,6 @@ sphinx: # Options passed on to the
use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo)
launch_buttons:
thebe: true # Required for live code: https://teachbooks.io/manual/features/live_code.html
favicon : "figures/TB_favicon.ico" # Replace this with your own favicon
baseurl : "https://<user/org>.io/<repo>" # Replace this with your own URL
html_show_copyright: false # As the copyright is included in the author field
html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer
html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s)

4
book/_toc.yml
View file

@ -20,6 +20,10 @@ parts:
sections:
- file: syntax_exercises/007.md
- file: syntax_exercises/008.md
- file: syntax_exercises/009.md
- file: syntax_exercises/010.md
- file: syntax_exercises/011.md
- file: syntax_exercises/012.md
- file: references.md
- file: changelog.md
- file: credits.md

4
book/syntax_exercises/008.md
View file

@ -35,8 +35,8 @@ align: center
Make sure the file extension of your figure is correct because markdown differentiates capital letters!
```
```{Warning}
If your figure is in a different directory than your chapter, you'll need to refer it using relative parts. If your figure is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `figures/<figure in figures-subdirectory>.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/<figure in figures-subdirectory which is located two folders above the current page>` )
```{tip}
If your figure is in a different directory than your chapter, you'll need to refer it using relative parts. If your figure is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `<subdirectory>/<figure in subdirectory>.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../<subdirectory>/<figure which is located in a subdirectory two folders above the current page.png>` )
```
6. To link and display an online figure, you can use the same `{figure}` directive. Just past in the :

93
book/syntax_exercises/009.md Normal file
View file

@ -0,0 +1,93 @@
# Exercise 9: Use equations
In this exercise, you will learn how to write and format mathematical equations in your TeachBook, both inline and as standalone blocks.
::::::{topic} Exercise objective
Can you write and format equations correctly in your book?
::::::
```{tip}
Using properly formatted equations makes mathematical expressions clearer and more professional. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/math.html).
```
## Writing equations
1. Open a new or existing Markdown file where you want to include an equation.
2. Start with a simple block equation using double dollar signs. Try adding the following equation in your Markdown file:
```md
$$ F_{res} = m \cdot a $$
```
```{tip}
The syntax used for creation equations is TeX, a markup language for math. It's often part of the software-system LaTeX, which allows to create full documents in this language. There's plenty of documentation online on how to use it, including graphical interfaces (for example [this one](https://latexeditor.lagrida.com/))
```
3. Now let's add another equation with an error:
```md
$$ E = m \ccdot c^2 $$
```
4. Check whether the equations renders correctly by clicking `preview` if you're making this edit in the GitHub single file editor. Make sure you already defined the file type as `<title>.md` to enable rendering. Note that all ill-formatted equation are indicated in red, i.e. $\red{\text{\ccdot}}$
5. As an alternative you try and use the 'math directive'. This will have the same results + adds a equation number which can be used for referencing (refer to [](011.md)):
````md
```{math}
v = a \cdot t
```
````
6. Click on `preview` again. Note that these equations don't render. That's because these 'directives' is a MyST feature (an extension of markdown), which is not supported by the GitHub previewer that only support markdown.
7. Now, add an inline equation by enclosing the equation with single dollar signs. Try this example:
```md
The displacement can be found using the equation $s = v \cdot t$.
```
## Formatting mathematical symbols
8. In this step we will experiment with different TeX symbols. Use the following table and test each example in your Markdown file:
| Name | Script |
|---|---|
| Square root | `\sqrt{4}` |
| Power | `^{2x}` |
| Fraction | `\frac{2}{3}` |
| Subscript | `_{gem}` |
| Superscript | `^{N}` |
| Multiplication | `\cdot` |
9. Extend this exercise by trying more advanced mathematical expressions:
| Name | Script |
|---|---|
| Derivative | `\frac{\Delta f}{\Delta t}` |
| Integral | `\int_a^b dx` |
| Sine function | `\sin(x)` |
10. Test your understanding by adding a new equation of your choice, ideally one that requires many LaTex symbols!
11. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
12. Add a commit message.
13. 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).
14. 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 to the next exercise, make sure you understand the following:
- What is the difference between inline and block equations?
- How do you use TeX formatting for different mathematical symbols?
- What is the purpose of using single vs. double dollar signs for equations?
- How do you troubleshoot if your equations are not rendering correctly?
```

86
book/syntax_exercises/010.md Normal file
View file

@ -0,0 +1,86 @@
# Exercise 10: Create tables
In this exercise, we will explore how to create and format tables in your TeachBook using Markdown and reStructuredText.
::::::{topic} Exercise objective
Can you correctly format tables within your book?
::::::
```{tip}
Tables help organize and present structured data clearly. JupyterBook supports raw markdown tables and MyST directives
```
## Writing Tables with Markdown
1. Open a new or existing Markdown file where you want to insert a table.
2. Add a simple table using the `|` separator and `---` for column alignment. [Other alignment options](https://www.markdownguide.org/extended-syntax/#alignment) are available too. Try the following example:
```md
| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Data 1 | Data 2 | Data 3 |
| Data 4 | Data 5 | Data 6 |
```
```{tip}
The syntax to type a table is a bit cumbersome. You could make use of online tools like [this one](https://www.tablesgenerator.com/markdown_tables) if you don't want to do all the typing yourself. This tool even allows copy pasting from Microsoft Excel!
```
3. Check whether the tables renders correctly by clicking `preview` if you're making this edit in the GitHub single file editor Make sure you already defined the file type as `<title>.md` to enable rendering. If the table is ill-formatted, not all data is shown, or the table is not rendered but shown as raw text.
## Creating Tables with directives
4. You can also use the `table` directive to create tables with additional formatting options: captions and [layout options](https://myst-parser.readthedocs.io/en/latest/syntax/tables.html#table-with-captions). Furthermore, this method allows referencing (refer to [](011.md)) Try it with the following example:
````md
```{table} Table caption
:widths: auto
:align: center
| Header 1 | Header 2 | Header 3 |
|---------------|---------------|---------------|
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |
```
````
5. Check the `Preview` again, note that the table is not rendered. That's because these 'directives' is a MyST feature (an extension of markdown), which is not supported by the GitHub previewer that only support markdown.
6. You can also create tables using the `list-table` directive. Use the code below to try this out.
````md
```{list-table} Sample Data Table
:header-rows: 1
* - Category
- Value 1
- Value 2
* - Item A
- 10
- 20
* - Item B
- 15
- 30
```
````
7. To test your understanding, try and create a new table from scratch with at least three columns, ensuring proper alignment and formatting, using both methods described above.
8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
9. Add a commit message.
10. 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).
11. 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 to the next exercise, make sure you understand the following:
- How do you create a basic table using Markdown?
- When would you choose to use a `table` instead of just a Markdown table?
- How do you specify column headers in a `list-table`?
```

180
book/syntax_exercises/011.md Normal file
View file

@ -0,0 +1,180 @@
# Exercise 11: Cross-referencing content
In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables and figures, as well as links.
::::::{topic} Exercise objective
Can you create internal references to other sections, equations, tables, figures, and links?
::::::
```{tip}
Referencing elements properly ensures that readers can navigate your book more easily. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/references.html).
```
## Referencing a Chapter or Section
1. Open a new or existing Markdown file where you want to add a reference.
2. Let's start with the simplest way to create a reference to another chapter. Try this out by directly linking the chapter through the file path as shown in the following syntax.
```md
[Text to display](path/to/file.md)
```
For example, if you want to link to Exercise 7, you can write:
```md
[Go to Exercise 7](../exercises/007.md)
```
If you leave the text part empty, the title of the chapter you're referring to will be used:
```md
[](path/to/file.md)
```
```{tip}
If the chapter you're referring to is in different directory than your chapter, you'll need to refer it using relative parts. If the to be referenced chapter is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `<subdirectory>/<chapter in subdirectory>.md`). If the to be referenced chapter is in another directory, move upwards with `../` (e.g. `../../<subdirectory>/<chapter which is located in a subdirectory two folders above the current page.md>` )
```
3. If we want to refer to a section within the same file, we can use local refencing by directly inputting the name of the required section. Use the example below to test this out.
```md
[Jump to the next section](#referencing-an-equation)
```
4. Try out another way of referencing by using a target header. Navigate to the chapter or section you want to reference and assign it an identifier within brackets as shown in the example below. This could be once again in the same markdown file, or a different file in the same repository.
```md
(exercise_1)=
# Exercise 1: First file edit
Let's start with the most basic edit: add some text to a file and see that the website is updated...
```
5. Now, let's explore three different ways to reference this section or chapter! For the first method, we use the standard title text by calling the identifier as follows.
```md
My favourite exercise was {ref}`exercise_1`.
```
6. For the second method, we want to refer to the section using a custom title text. Try this out by placing the text that you want to be displayed within `` and calling the identifier within <>.
```md
My favourite exercise was {ref}`the first one <exercise_1>`.
```
7. The last method uses markdown syntax to also display a custom title text. Refer to the desired section once again, this time by putting the custom text within [] and calling the identifier within <> as shown below.
```md
My favourite exercise was [this one](exercise_1).
```
## Referencing an Equation
8. Now we will test our knowledge using an equation (as implemented before in [](009.md)). Similar to the code below, create an equation using $$ and identify it using a label within the brackets.
```md
$$ F = m \cdot a$$ (eq:Newton)
```
$$ F = m \cdot a$$ (eq:Newton)
9. Refer to this equation by using `{eq}` and calling the identifier within the ``. This will automatically insert the number of the equation. You can add text as you did in exercise 6.
```md
Refer to Equation {eq}`eq:Newton`
```
Alternatively, you can use the default `[<text to display>](<identifier>)`.
## Referencing a Table
10. Similar methods can also be used to refer to a table (as implemented before in [](010.md)). Start by creating a table by copying the code below. The identifier is defined using `:name:`.
````md
```{table} Example Table
:name: tab-example
| Column 1 | Column 2 |
|----------|----------|
| A | B |
```
````
```{table} Example Table
:name: tab-example
| Column 1 | Column 2 |
|----------|----------|
| A | B |
```
11. Refer to the table like with custom text 'My table' and the number using `{numref}` and `{number}` as follows. You can add text as you did in exercise 6.
```md
{numref}`My table {number} <tab-example>`
```
Alternatively, you get an automatic text 'Table ' and the number when using `` {numref}`<tab-example>` ``. Or use `{ref}` to use the table name instead of number. Next to all of that you can use the default `[<Eventually text to display, otherwise use title>](<table name>)`.
## Referencing a Figure
12. This can also be done for a figure. Let's add a figure as we learnt to do in [Exercise 8](008.md), but this time adding an identifier using `name:`.
````md
```{figure} figures/example.png
---
width: 80%
align: center
name: fig-example
---
Example figure.
```
````
13. Refer to the figure in the with custom text 'Figure' and the number using `{numref}` as follows. You can add text as you did in exercise 6.
```md
{numref}`Figure {number} <fig-example>`
```
Alternatively, you get an automatic text 'Fig.' and the number when using `` {numref}`<fig-example>` ``. Or use `{ref}` to use the figure name instead of number. Next to all of that you can use the default `[<Eventually text to display, otherwise use title>](<figure name>)`.
## Referencing a Link
14. Finally, let's reference a link, using the following syntax:
```md
[Text to display](url)
```
For example, you can use the code.
```md
Here is the [link to the template](https://teachbooks.github.io/template/).
```
15. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
16. Add a commit message.
17. To see your changes, go to {octicon}`play;1em` `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).
18. 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 to the next exercise, make sure you understand the following:
- How do you reference another chapter or section?
- How do you create a reference to an equation, table or figure in your book?
- How do you reference a link?
```

220
book/syntax_exercises/012.md Normal file
View file

@ -0,0 +1,220 @@
# Exercise 12: Use admonitions
In this exercise, you will learn how to use admonitions to enhance the readability and structure of your TeachBook content. Admonitions are special highlighted blocks that are useful for tips, warnings, notes, and more.
::::::{topic} Exercise objective
Can you structure your content with different types of admonitions and understand which can be customised?
::::::
```{tip}
Admonitions help to guide readers' attention and make your book more accessible. Full documentation is available [here for the default MyST syntax in your book](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html) and [here for the TeachBooks' extension which allows custom colours](https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html#admonitions).
```
## Using standard admonitions
1. Open a new or existing Markdown file.
2. Start by adding a simple `note` admonition. This type uses a **fixed title** ("Note"):
````md
```{note}
This is a note. It always has the title "Note".
```
````
3. Try adding the following fixed-title admonitions. These cannot have custom titles:
````md
```{tip}
This is a helpful tip!
```
```{warning}
Be careful when editing this file.
```
```{attention}
Important: Save your work frequently.
```
````
4. Other fixed-title admonitions are listed below. Try use these in your code using the same format used above.
- `caution`
- `important`
- `seealso`
- `error`
- `hint`
- `danger`
## Custom titles & styles for admonitions
5. Some admonitions allow you to **specify your own title**. Try the `admonition` directive:
````md
```{admonition} Did you know?
You can customise the title of this block using the `admonition` directive.
```
````
6. Similarly, you can customise titles for `dropdown` admonitions:
````md
```{dropdown} Click to reveal more info
This content is hidden until the user clicks the title.
```
````
7. Dropdowns are great for optional or expandable content. Try nesting content inside a dropdown block::
````md
```{dropdown} See the steps
1. Open your file.
2. Write some content.
3. Preview the changes.
```
````
8. Check your understanding with the summary table below.
```{admonition} Summary: Fixed vs. Custom Title Admonitions
Here’s a quick overview:
| Fixed Title Admonitions | Custom Title Admonitions |
|------------------------------------------------------------------|-------------------------------|
| `note`, `tip`, `warning`, `attention`, `caution`, `important`, `seealso`, `hint`, `danger`, `error` | `admonition`, `dropdown` |
```
9. For these admonitions that allow custom titles (`admonition`, `dropdown`), you can also apply a **custom style** using the `:class:` option. This can be used to change the appearance (e.g. colour or layout) of the block. Try the following examples:
````md
```{admonition} Pro tip!
:class: tip
You can apply styles using the `:class:` option.
```
````
````md
```{dropdown} Save your work
:class: warning
Don't forget to save your changes regularly to avoid data loss!
```
````
10. You can apply the `:class: dropdown` to any `admonition`, even if it is not originally a dropdown block. This will allow the admonition to be collapsible, making it useful for sections where you'd like to hide additional content until the reader clicks to expand it. Test this out:
````md
```{admonition} Extra Info
:class: dropdown
This content will be hidden until the reader clicks to reveal it.
```
````
11. The table below summarizes the classes that can be used together with the `admonition` and `dropdown` blocks. Try customize admonitions yourself, using different classes from the table.
| Class name | Effect |
|------------------|------------------------------------------------------------------------|
| `tip` | Gives the block a green background (styled like a helpful tip) |
| `warning` | Orange background with a warning-style border |
| `caution` | Yellow caution-style background |
| `error` / `danger` | Red background indicating errors or important warnings |
| `dropdown` | Makes the block collapsible (content is hidden until clicked) |
| `seealso` | Blue background, often used for related info or references |
| `important` | Dark blue or purple background for emphasis |
| `note` | Subtle grey note block |
12. You can also use **multiple classes** at once by separating them with spaces. For example, `:class: important dropdown` will give you a collapsible, important-looking block. Try mixing and matching these, using the example below as a base:
````md
```{admonition} Important: Check this out!
:class: important dropdown
This content is both highlighted as important and collapsible.
```
````
## Custom colours for admonitions
13. It is also possible to use specific colours to customize your admonitions, using our extension ['Sphinx-Named-Colours'](https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html#admonitions). This allow you to use default 'CSS' colours or your own custom colours. To do so, it is necessary to add the extension as shown below. Note that in this template book, this is already done for you, let's check that!
**Step A: Add to `requirements.txt`**
Ensure that the package is included in your project's `requirements.txt` (in the root of your repository) to make it available:
```
.
.
.
sphinx-named-colors
.
.
.
```
**Step B: Enable in `_config.yml`**
In your `_config.yml` file (in the `book/` subdirectory of your repository), ensure that the extension is added to the list of Sphinx extra extensions so that it's included in the building of your book:
```md
sphinx:
extra_extensions:
.
.
.
- sphinx_named_colors
.
.
.
```
14. Now we can experiment with custom-coloured admonitions! Go ahead and look at the available [CSS Named Colours](https://developer.mozilla.org/en-US/docs/Web/CSS/named-color), and pick a desired colour.
15. Once you have chosen a colour, coloured admonitions can be generated in two ways, depending on how you'd like to structure your content. The first method is by adding the name-colour via `:class:` to an existing `admonition` or `dropdown` type block, similar to what was done above. This can be done as follows:
````md
```{admonition} Custom Colour Example 1
:class: darkred
This is a custom coloured admonition using `:class: darkred`.
```
````
16. The second method of adding coloured admonitions is by directly creating an admonition based on a colour. This method can be used if you'd rather not use the generic type and want a minimal syntax. In this case, the title is optional, and if omitted, the title bar will not appear. Try this out with the code below:
````md
```{darkgreen} Optional Title with custom coluor example 2
This is a green-styled custom admonition.
```
````
17. For more details, see the documentation of this extension in [our manual](https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html). This also describes how to add your own custom colours!
18. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
19. Add a commit message.
20. 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).
21. 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:
- Which admonitions allow custom titles, and which don’t?
- What is the purpose of a dropdown admonition?
- When might you use a `note` vs. an `admonition`?
- In which ways can you further customize `admonition` blocks?
```