From d27b8e6f85bce8d5437dda0c16d849befd3715aa Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Thu, 20 Mar 2025 12:34:10 +0100 Subject: [PATCH 01/57] Exercise 9 --- book/syntax_exercises/009.md | 100 +++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 book/syntax_exercises/009.md diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md new file mode 100644 index 0000000..9c12cc9 --- /dev/null +++ b/book/syntax_exercises/009.md @@ -0,0 +1,100 @@ +# Exercise 9: Cross-referencing content + +In this exercise, you will learn how to create references to other parts of your book, such as chapters, equations, tables, and figures. + +::::::{topic} Exercise objective +Can you create internal references to other sections, equations, tables, and figures? +:::::: + +```{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). +``` + +## 1. Referencing a Chapter or Section + +To create a reference to another chapter or section, use 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) +``` + + +## 2. Referencing an Equation + +To reference an equation, you need to define a label using `{eq}` and refer to it elsewhere in your text: + +```md +```{math} +:label: eq-example +E = mc^2 +``` +``` + +You can then reference this equation using: + +```md +Equation {eq}`eq-example` +``` + +## 3. Referencing a Table + +To reference a table, assign a label when defining it: + +```md +```{table} Example Table +:label: tab-example +| Column 1 | Column 2 | +|----------|----------| +| A | B | +``` +``` + +And refer to it using: + +```md +Table {numref}`tab-example` +``` + +## 4. Referencing a Figure + +To reference a figure, label it when inserting it: + +```md +```{figure} figures/example.png +--- +width: 80% +align: center +name: fig-example +--- +Example figure. +``` +``` + +And refer to it using: + +```md +Figure {numref}`fig-example` +``` + +## 5. Commit Your Changes + +1. Once you have added your references, commit your changes to the repository. +2. Click the green `Commit changes` button. +3. Add a commit message. +4. View your changes using the `Actions` tab and check if they appear correctly. + +```{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? +- How do you create a reference to an equation? +- How can you refer to a table or a figure in your book? + +``` \ No newline at end of file From b3fce913d0998c3b5ec49e5f42035b370f53ae2d Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Thu, 20 Mar 2025 12:35:30 +0100 Subject: [PATCH 02/57] toc exercise 9 --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index ad5003f..91a0b9f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -20,6 +20,7 @@ parts: sections: - file: syntax_exercises/007.md - file: syntax_exercises/008.md + - file: syntax_exercises/009.md - file: references.md - file: changelog.md - file: credits.md From cddce2ffe5ed89968dfe1048ffc28487a6d56846 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 21 Mar 2025 09:13:39 +0100 Subject: [PATCH 03/57] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 91a0b9f..373feb7 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -20,7 +20,7 @@ parts: sections: - file: syntax_exercises/007.md - file: syntax_exercises/008.md - - file: syntax_exercises/009.md + - file: syntax_exercises\009.md - file: references.md - file: changelog.md - file: credits.md From b0854fe677607e37d3a9b6c9c412c9ebf9ad3101 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 21 Mar 2025 09:17:37 +0100 Subject: [PATCH 04/57] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 373feb7..91a0b9f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -20,7 +20,7 @@ parts: sections: - file: syntax_exercises/007.md - file: syntax_exercises/008.md - - file: syntax_exercises\009.md + - file: syntax_exercises/009.md - file: references.md - file: changelog.md - file: credits.md From 8461fc30e3a51efe27d1631973283716b6e9dffb Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 21 Mar 2025 09:27:51 +0100 Subject: [PATCH 05/57] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 91a0b9f..f0ab122 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -23,4 +23,4 @@ parts: - file: syntax_exercises/009.md - file: references.md - file: changelog.md - - file: credits.md + - file: credits.md \ No newline at end of file From a1e1f6c1a66599e33b2a411a2cf7937b272876ce Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 21 Mar 2025 09:32:26 +0100 Subject: [PATCH 06/57] Update _toc.yml --- book/_toc.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index f0ab122..ad5003f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -20,7 +20,6 @@ parts: sections: - file: syntax_exercises/007.md - file: syntax_exercises/008.md - - file: syntax_exercises/009.md - file: references.md - file: changelog.md - - file: credits.md \ No newline at end of file + - file: credits.md From 66fb69a7df08621267828d0f2aec6fd989176f67 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 21 Mar 2025 09:35:15 +0100 Subject: [PATCH 07/57] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index ad5003f..91a0b9f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -20,6 +20,7 @@ parts: sections: - file: syntax_exercises/007.md - file: syntax_exercises/008.md + - file: syntax_exercises/009.md - file: references.md - file: changelog.md - file: credits.md From 5f44447e7e197bdae82e565076ed95d2b7f08f1a Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Fri, 21 Mar 2025 10:16:23 +0100 Subject: [PATCH 08/57] bump --- book/syntax_exercises/009.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 9c12cc9..14111bc 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -1,6 +1,6 @@ # Exercise 9: Cross-referencing content -In this exercise, you will learn how to create references to other parts of your book, such as chapters, equations, tables, and figures. +In this exercise, you will learn how to create references to other parts of your book, such as chapters, equations, tables, and figures. ::::::{topic} Exercise objective Can you create internal references to other sections, equations, tables, and figures? From b33df99f2b7ce599c5717bdba72aa56bbc96cbf0 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 22 Mar 2025 16:39:31 +0100 Subject: [PATCH 09/57] Update 009.md --- book/syntax_exercises/009.md | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 14111bc..7b071a2 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -1,6 +1,6 @@ # Exercise 9: Cross-referencing content -In this exercise, you will learn how to create references to other parts of your book, such as chapters, equations, tables, and figures. +In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables, and figures. ::::::{topic} Exercise objective Can you create internal references to other sections, equations, tables, and figures? @@ -24,6 +24,36 @@ For example, if you want to link to Exercise 7, you can write: [Go to Exercise 7](../exercises/007.md) ``` +Alternatively, you can use `{ref}` to reference a section with a target header. + +First, define the section you want to reference by assigning it an identifier: + +```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... +``` + +Then, you can reference this section in three ways: + +- Using the standard title text: + ```md + My favourite exercise was {ref}`exercise_1`. + ``` + This will display: *My favourite exercise was Exercise 1: First file edit.* + +- Specifying a custom title text: + ```md + My favourite exercise was {ref}`the first one `. + ``` + This will display: *My favourite exercise was the first one.* + +- Using Markdown syntax: + ```md + My favourite exercise was [this one](exercise_1). + ``` + This will display: *My favourite exercise was this one.* ## 2. Referencing an Equation @@ -93,8 +123,6 @@ Figure {numref}`fig-example` :class: note Before moving on to the next exercise, make sure you understand the following: -- How do you reference another chapter? +- How do you reference another chapter or section? - How do you create a reference to an equation? - How can you refer to a table or a figure in your book? - -``` \ No newline at end of file From 36cd95409555d6d8c99c51a545cc1d002730a6ca Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 22 Mar 2025 17:30:17 +0100 Subject: [PATCH 10/57] updated content --- book/syntax_exercises/009.md | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 7b071a2..70d37f1 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -41,19 +41,19 @@ Then, you can reference this section in three ways: ```md My favourite exercise was {ref}`exercise_1`. ``` - This will display: *My favourite exercise was Exercise 1: First file edit.* + This will display: My favourite exercise was {ref}`exercise_1`. - Specifying a custom title text: ```md My favourite exercise was {ref}`the first one `. ``` - This will display: *My favourite exercise was the first one.* + This will display: My favourite exercise was {ref}`the first one `. - Using Markdown syntax: ```md My favourite exercise was [this one](exercise_1). ``` - This will display: *My favourite exercise was this one.* + This will display: My favourite exercise was [this one](exercise_1). ## 2. Referencing an Equation @@ -72,6 +72,10 @@ You can then reference this equation using: Equation {eq}`eq-example` ``` +This will display: Equation {eq}`eq-example`. + + + ## 3. Referencing a Table To reference a table, assign a label when defining it: @@ -112,7 +116,25 @@ And refer to it using: Figure {numref}`fig-example` ``` -## 5. Commit Your Changes +## 5. Referencing a Link + +To reference a link, use the following syntax: + +```md +[Text to display](https://teachbooks.github.io/template/) +``` +For example, you can write: + +```md +Here is the [link to the template](https://teachbooks.github.io/template/). +``` + +This wil display: Here is the [link to the template](https://teachbooks.github.io/template/). + + + + +## 6. Commit Your Changes 1. Once you have added your references, commit your changes to the repository. 2. Click the green `Commit changes` button. @@ -124,5 +146,5 @@ Figure {numref}`fig-example` 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? -- How can you refer to a table or a figure in your book? +- How do you create a reference to an equation, table or figure in your book? +- How do you reference a link? From 2d74872a6e0a492ebd523a2f417b925a729c751a Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 22 Mar 2025 17:51:05 +0100 Subject: [PATCH 11/57] Update 009.md --- book/syntax_exercises/009.md | 41 ++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 70d37f1..abe02a6 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -1,9 +1,7 @@ -# Exercise 9: 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. +In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables, figures, and links. ::::::{topic} Exercise objective -Can you create internal references to other sections, equations, tables, and figures? +Can you create internal references to other sections, equations, tables, figures, and links? :::::: ```{tip} @@ -55,15 +53,19 @@ Then, you can reference this section in three ways: ``` This will display: My favourite exercise was [this one](exercise_1). +These three referencing methods can also be used for referencing equations, tables and figures. + ## 2. Referencing an Equation To reference an equation, you need to define a label using `{eq}` and refer to it elsewhere in your text: ```md + ```{math} :label: eq-example E = mc^2 ``` + ``` You can then reference this equation using: @@ -72,8 +74,6 @@ You can then reference this equation using: Equation {eq}`eq-example` ``` -This will display: Equation {eq}`eq-example`. - ## 3. Referencing a Table @@ -81,12 +81,12 @@ This will display: Equation {eq}`eq-example`. To reference a table, assign a label when defining it: ```md -```{table} Example Table -:label: tab-example -| Column 1 | Column 2 | -|----------|----------| -| A | B | -``` + ```{table} Example Table + :label: tab-example + | Column 1 | Column 2 | + |----------|----------| + | A | B | + ``` ``` And refer to it using: @@ -95,19 +95,20 @@ And refer to it using: Table {numref}`tab-example` ``` + ## 4. Referencing a Figure To reference a figure, label it when inserting it: ```md -```{figure} figures/example.png ---- -width: 80% -align: center -name: fig-example ---- -Example figure. -``` + ```{figure} figures/example.png + --- + width: 80% + align: center + name: fig-example + --- + Example figure. + ``` ``` And refer to it using: From cfdcfe8482e60f82b6408a83923c04577a2503dc Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 22 Mar 2025 17:59:12 +0100 Subject: [PATCH 12/57] final changes 09 --- book/syntax_exercises/009.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index abe02a6..f3730e6 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -1,4 +1,6 @@ -In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables, figures, and links. +# Exercise 9: 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? @@ -57,14 +59,14 @@ These three referencing methods can also be used for referencing equations, tabl ## 2. Referencing an Equation -To reference an equation, you need to define a label using `{eq}` and refer to it elsewhere in your text: +To reference an equation, you need to define a label when creating the equation and refer to it elsewhere in your text using `{eq}`: ```md -```{math} -:label: eq-example -E = mc^2 -``` + ```{math} + :label: eq-example + E = mc^2 + ``` ``` @@ -89,7 +91,7 @@ To reference a table, assign a label when defining it: ``` ``` -And refer to it using: +And refer to it using `{numref}`: ```md Table {numref}`tab-example` @@ -111,7 +113,7 @@ To reference a figure, label it when inserting it: ``` ``` -And refer to it using: +And refer to it using `{numref}`: ```md Figure {numref}`fig-example` From 8370b7e62f059ca5e6360b7aa7fcc304703178ba Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 24 Mar 2025 23:30:52 +0100 Subject: [PATCH 13/57] update 009 24/03 --- book/syntax_exercises/009.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index f3730e6..8b23a46 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -12,7 +12,8 @@ Referencing elements properly ensures that readers can navigate your book more e ## 1. Referencing a Chapter or Section -To create a reference to another chapter or section, use the following syntax: +1. Open the Markdown file where you want to add a reference. +2. Lets start with the simplest way to create a reference to another chapter or section. This is by directly linking it through the file path as shown in the following syntax: ```md [Text to display](path/to/file.md) @@ -23,10 +24,7 @@ For example, if you want to link to Exercise 7, you can write: ```md [Go to Exercise 7](../exercises/007.md) ``` - -Alternatively, you can use `{ref}` to reference a section with a target header. - -First, define the section you want to reference by assigning it an identifier: +3. 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 using `{ref}` as shown in the example below. ```md (exercise_1)= @@ -34,22 +32,23 @@ First, define the section you want to reference by assigning it an identifier: Let's start with the most basic edit: add some text to a file and see that the website is updated... ``` +4. Now, lets explore three different ways to reference this section! For the first method, we use the standard title text by calling the identifier as follows: -Then, you can reference this section in three ways: - -- Using the standard title text: ```md My favourite exercise was {ref}`exercise_1`. ``` This will display: My favourite exercise was {ref}`exercise_1`. -- Specifying a custom title text: +5. 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 the `` and calling the identifier within the <> as follows: + ```md My favourite exercise was {ref}`the first one `. ``` This will display: My favourite exercise was {ref}`the first one `. -- Using Markdown syntax: +6. The final 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 the [] and calling the identifier within the <> as shown below: + + ```md My favourite exercise was [this one](exercise_1). ``` From 0b29820e46441d42e767fa6f63c17d8d2f9d184f Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 25 Mar 2025 22:44:04 +0100 Subject: [PATCH 14/57] update 9.2 --- book/syntax_exercises/009.md | 45 ++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 8b23a46..924bacd 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -12,8 +12,8 @@ Referencing elements properly ensures that readers can navigate your book more e ## 1. Referencing a Chapter or Section -1. Open the Markdown file where you want to add a reference. -2. Lets start with the simplest way to create a reference to another chapter or section. This is by directly linking it through the file path as shown in the following syntax: +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. This is by directly linking it through the file path as shown in the following syntax: ```md [Text to display](path/to/file.md) @@ -24,7 +24,7 @@ For example, if you want to link to Exercise 7, you can write: ```md [Go to Exercise 7](../exercises/007.md) ``` -3. 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 using `{ref}` as shown in the example below. +3. 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 using `{ref}` as shown in the example below. This could be either in the same markdown file, or a different file altogether. ```md (exercise_1)= @@ -32,13 +32,14 @@ For example, if you want to link to Exercise 7, you can write: Let's start with the most basic edit: add some text to a file and see that the website is updated... ``` -4. Now, lets explore three different ways to reference this section! For the first method, we use the standard title text by calling the identifier as follows: +4. 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`. ``` This will display: My favourite exercise was {ref}`exercise_1`. + 5. 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 the `` and calling the identifier within the <> as follows: ```md @@ -46,6 +47,7 @@ Let's start with the most basic edit: add some text to a file and see that the w ``` This will display: My favourite exercise was {ref}`the first one `. + 6. The final 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 the [] and calling the identifier within the <> as shown below: @@ -58,23 +60,32 @@ These three referencing methods can also be used for referencing equations, tabl ## 2. Referencing an Equation -To reference an equation, you need to define a label when creating the equation and refer to it elsewhere in your text using `{eq}`: +7. Now we will test our knowledge using an equation. 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) + + ``` + +This will display as follows: + + $$ F = m \cdot a$$ (eq:Newton) + +8. In this step, we will use the three referencing methods discussed above to reference this equation as follows: + ```md - - ```{math} - :label: eq-example - E = mc^2 - ``` - -``` - -You can then reference this equation using: - -```md -Equation {eq}`eq-example` +Refer to Equation {eq}`eq:Newton` +Refer to the {eq}'above equation ' +Refer to [this equation](eq:Newton) ``` +These will display as: +Refer to Equation {eq}`eq:Newton` +Refer to the {eq}'above equation ' +Refer to [this equation](eq:Newton) ## 3. Referencing a Table From c574592c841ccec2ee45cede57cd7e99c6ed4767 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 25 Mar 2025 23:27:06 +0100 Subject: [PATCH 15/57] update rest of 9 --- book/syntax_exercises/009.md | 78 ++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 35 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 924bacd..e2dc43f 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -24,7 +24,16 @@ For example, if you want to link to Exercise 7, you can write: ```md [Go to Exercise 7](../exercises/007.md) ``` -3. 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 using `{ref}` as shown in the example below. This could be either in the same markdown file, or a different file altogether. + +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. + +```md +[Jump to the next section](# 2. Referencing an Equation) +``` +[Jump to the next section](# 2. 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 using `{ref}` as shown in the example below. This could be once again in the same markdown file, or a different file altogether. ```md (exercise_1)= @@ -32,7 +41,7 @@ For example, if you want to link to Exercise 7, you can write: Let's start with the most basic edit: add some text to a file and see that the website is updated... ``` -4. 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: +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`. @@ -40,7 +49,7 @@ Let's start with the most basic edit: add some text to a file and see that the w This will display: My favourite exercise was {ref}`exercise_1`. -5. 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 the `` and calling the identifier within the <> as follows: +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 the `` and calling the identifier within the <> as follows: ```md My favourite exercise was {ref}`the first one `. @@ -48,7 +57,7 @@ Let's start with the most basic edit: add some text to a file and see that the w This will display: My favourite exercise was {ref}`the first one `. -6. The final 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 the [] and calling the identifier within the <> as shown below: +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 the [] and calling the identifier within the <> as shown below: ```md @@ -56,11 +65,11 @@ Let's start with the most basic edit: add some text to a file and see that the w ``` This will display: My favourite exercise was [this one](exercise_1). -These three referencing methods can also be used for referencing equations, tables and figures. + ## 2. Referencing an Equation -7. Now we will test our knowledge using an equation. Similar to the code below, create an equation using $$ and identify it using a label within the brackets. +8. Now we will test our knowledge using an equation. Similar to the code below, create an equation using $$ and identify it using a label within the brackets. ```md @@ -69,48 +78,46 @@ These three referencing methods can also be used for referencing equations, tabl ``` -This will display as follows: - $$ F = m \cdot a$$ (eq:Newton) -8. In this step, we will use the three referencing methods discussed above to reference this equation as follows: - +8. To refer to this equation we need to use {eq} and call the identifier within the ``. This will display: Refer to Equation {eq}`eq:Newton`. ```md Refer to Equation {eq}`eq:Newton` -Refer to the {eq}'above equation ' -Refer to [this equation](eq:Newton) ``` -These will display as: - -Refer to Equation {eq}`eq:Newton` -Refer to the {eq}'above equation ' -Refer to [this equation](eq:Newton) ## 3. Referencing a Table -To reference a table, assign a label when defining it: +9. Similar methods can also be used to refer to a table. Start by creating a table by copying the markdown below. The identifier is defined using ':name:'. ```md ```{table} Example Table - :label: tab-example + :name: tab-example | Column 1 | Column 2 | |----------|----------| | A | B | ``` ``` -And refer to it using `{numref}`: +```{table} Example Table +name: tab-example +| Column 1 | Column 2 | +|----------|----------| +| A | B | +``` + +10. Refer to the table like {numref}`Table {number} ` using {numref} and {number} as follows: + ```md -Table {numref}`tab-example` +{numref}`Table {number} ` ``` ## 4. Referencing a Figure -To reference a figure, label it when inserting it: +11. This can also be done for a figure. Let's add a figure as we learnt in [Exercise 7](007.md), but this time adding an identifier using 'name:'. ```md ```{figure} figures/example.png @@ -123,36 +130,37 @@ To reference a figure, label it when inserting it: ``` ``` -And refer to it using `{numref}`: +12. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: ```md -Figure {numref}`fig-example` +{numref}`Figure {number} ` ``` ## 5. Referencing a Link -To reference a link, use the following syntax: +13. Finally, lets reference a link, using the following syntax: ```md -[Text to display](https://teachbooks.github.io/template/) +[Text to display](url) ``` -For example, you can write: +For example, you can use the code below to display: Here is the [link to the template](https://teachbooks.github.io/template/). + ```md Here is the [link to the template](https://teachbooks.github.io/template/). ``` -This wil display: Here is the [link to the template](https://teachbooks.github.io/template/). - - - ## 6. Commit Your Changes -1. Once you have added your references, commit your changes to the repository. -2. Click the green `Commit changes` button. -3. Add a commit message. -4. View your changes using the `Actions` tab and check if they appear correctly. +14. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +15. Add a commit message. + +16. To see you 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). + +17. 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 From d7fc0a3a70dbb6cc283c90bae3f1de600bfb7aee Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 25 Mar 2025 23:51:57 +0100 Subject: [PATCH 16/57] Update 009.md --- book/syntax_exercises/009.md | 45 ++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 25 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index e2dc43f..63743c6 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -10,7 +10,7 @@ Can you create internal references to other sections, equations, tables, figures 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). ``` -## 1. Referencing a Chapter or Section +## 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. This is by directly linking it through the file path as shown in the following syntax: @@ -25,15 +25,14 @@ For example, if you want to link to Exercise 7, you can write: [Go to Exercise 7](../exercises/007.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. +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. For example: [Jump to the next section](#referencing-an-equation) ```md -[Jump to the next section](# 2. Referencing an Equation) +[Jump to the next section](#referencing-an-equation) ``` -[Jump to the next section](# 2. 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 using `{ref}` as shown in the example below. This could be once again in the same markdown file, or a different file altogether. +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 using `{ref}` 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)= @@ -41,33 +40,30 @@ For example, if you want to link to Exercise 7, you can write: 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: +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. This will display: My favourite exercise was {ref}`exercise_1`. ```md My favourite exercise was {ref}`exercise_1`. ``` - This will display: 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 the `` and calling the identifier within the <> as follows: +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 <>. +This will display: My favourite exercise was {ref}`the first one `. ```md My favourite exercise was {ref}`the first one `. ``` - This will display: My favourite exercise was {ref}`the first one `. -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 the [] and calling the identifier within the <> as shown below: +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 the [] and calling the identifier within the <> as shown below. This will display: My favourite exercise was [this one](exercise_1). ```md My favourite exercise was [this one](exercise_1). ``` - This will display: My favourite exercise was [this one](exercise_1). - -## 2. Referencing an Equation +## Referencing an Equation 8. Now we will test our knowledge using an equation. Similar to the code below, create an equation using $$ and identify it using a label within the brackets. @@ -80,25 +76,26 @@ Let's start with the most basic edit: add some text to a file and see that the w $$ F = m \cdot a$$ (eq:Newton) -8. To refer to this equation we need to use {eq} and call the identifier within the ``. This will display: Refer to Equation {eq}`eq:Newton`. +8. To refer to this equation we need to use `{eq}` and call the identifier within the `` to achieve: Refer to Equation {eq}`eq:Newton`. ```md Refer to Equation {eq}`eq:Newton` ``` -## 3. Referencing a Table +## Referencing a Table -9. Similar methods can also be used to refer to a table. Start by creating a table by copying the markdown below. The identifier is defined using ':name:'. +9. Similar methods can also be used to refer to a table. Start by creating a table by copying the code below. The identifier is defined using `:name:`. -```md + ```md ```{table} Example Table :name: tab-example | Column 1 | Column 2 | |----------|----------| | A | B | ``` -``` + ``` + ```{table} Example Table name: tab-example @@ -115,11 +112,11 @@ name: tab-example ``` -## 4. Referencing a Figure +## Referencing a Figure -11. This can also be done for a figure. Let's add a figure as we learnt in [Exercise 7](007.md), but this time adding an identifier using 'name:'. +11. This can also be done for a figure. Let's add a figure as we learnt to do in [Exercise 7](007.md), but this time adding an identifier using `name:`. -```md + ```md ```{figure} figures/example.png --- width: 80% @@ -128,7 +125,7 @@ name: tab-example --- Example figure. ``` -``` + ``` 12. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: @@ -136,7 +133,7 @@ name: tab-example {numref}`Figure {number} ` ``` -## 5. Referencing a Link +## Referencing a Link 13. Finally, lets reference a link, using the following syntax: @@ -151,8 +148,6 @@ Here is the [link to the template](https://teachbooks.github.io/template/). ``` -## 6. Commit Your Changes - 14. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. 15. Add a commit message. From 222cfedacdbe21a38a0b34034f275b8209579560 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 26 Mar 2025 00:01:22 +0100 Subject: [PATCH 17/57] Update 009.md --- book/syntax_exercises/009.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 63743c6..6fda948 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -25,14 +25,14 @@ For example, if you want to link to Exercise 7, you can write: [Go to Exercise 7](../exercises/007.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. For example: [Jump to the next section](#referencing-an-equation) +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. The code below gives: [Jump to the next section](#referencing-an-equation) ```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 using `{ref}` as shown in the example below. This could be once again in the same markdown file, or a different file in the same repository. +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)= @@ -55,7 +55,7 @@ This will display: My favourite exercise was {ref}`the first one `. ``` -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 the [] and calling the identifier within the <> as shown below. This will display: My favourite exercise was [this 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. This will display: My favourite exercise was [this one](exercise_1). ```md @@ -104,7 +104,7 @@ name: tab-example | A | B | ``` -10. Refer to the table like {numref}`Table {number} ` using {numref} and {number} as follows: +10. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows: ```md From 8df769acf7a3b4a218d8a9fb98f2eb94b5c024e0 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 26 Mar 2025 15:40:46 +0100 Subject: [PATCH 18/57] Update 009.md --- book/syntax_exercises/009.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 6fda948..3cbf0e1 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -13,7 +13,7 @@ Referencing elements properly ensures that readers can navigate your book more e ## 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. This is by directly linking it through the file path as shown in the following syntax: +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) @@ -25,7 +25,7 @@ For example, if you want to link to Exercise 7, you can write: [Go to Exercise 7](../exercises/007.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. The code below gives: [Jump to the next section](#referencing-an-equation) +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. This code gives: [Jump to the next section](#referencing-an-equation) ```md [Jump to the next section](#referencing-an-equation) @@ -76,7 +76,7 @@ This will display: My favourite exercise was {ref}`the first one `. $$ F = m \cdot a$$ (eq:Newton) -8. To refer to this equation we need to use `{eq}` and call the identifier within the `` to achieve: Refer to Equation {eq}`eq:Newton`. +8. Refer to this equation by using `{eq}` and calling the identifier within the `` to achieve: Refer to Equation {eq}`eq:Newton`. ```md Refer to Equation {eq}`eq:Newton` @@ -135,7 +135,7 @@ name: tab-example ## Referencing a Link -13. Finally, lets reference a link, using the following syntax: +13. Finally, let's reference a link, using the following syntax: ```md [Text to display](url) From 3a2db9bc6f666340c3728a5abd3df5d6ee4b195f Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 26 Mar 2025 15:50:13 +0100 Subject: [PATCH 19/57] updated numbering 09 --- book/syntax_exercises/009.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 3cbf0e1..f7c1720 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -76,7 +76,7 @@ This will display: My favourite exercise was {ref}`the first one `. $$ F = m \cdot a$$ (eq:Newton) -8. Refer to this equation by using `{eq}` and calling the identifier within the `` to achieve: Refer to Equation {eq}`eq:Newton`. +9. Refer to this equation by using `{eq}` and calling the identifier within the `` to achieve: Refer to Equation {eq}`eq:Newton`. ```md Refer to Equation {eq}`eq:Newton` @@ -85,16 +85,17 @@ Refer to Equation {eq}`eq:Newton` ## Referencing a Table -9. Similar methods can also be used to refer to a table. Start by creating a table by copying the code below. The identifier is defined using `:name:`. +10. Similar methods can also be used to refer to a table. 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 | ``` + ``` + ```{table} Example Table @@ -104,7 +105,7 @@ name: tab-example | A | B | ``` -10. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows: +11. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows: ```md @@ -114,7 +115,7 @@ name: tab-example ## Referencing a Figure -11. This can also be done for a figure. Let's add a figure as we learnt to do in [Exercise 7](007.md), but this time adding an identifier using `name:`. +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 @@ -127,7 +128,7 @@ name: tab-example ``` ``` -12. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: +13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: ```md {numref}`Figure {number} ` @@ -135,7 +136,7 @@ name: tab-example ## Referencing a Link -13. Finally, let's reference a link, using the following syntax: +14. Finally, let's reference a link, using the following syntax: ```md [Text to display](url) @@ -148,13 +149,13 @@ Here is the [link to the template](https://teachbooks.github.io/template/). ``` -14. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +15. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -15. Add a commit message. +16. Add a commit message. -16. To see you 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). +17. To see you 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). -17. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +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 From 278ac39643d074e04ba01a6e6175d91b9b1e60b3 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 26 Mar 2025 15:55:38 +0100 Subject: [PATCH 20/57] updated indent --- book/syntax_exercises/009.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index f7c1720..f526538 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -97,14 +97,6 @@ Refer to Equation {eq}`eq:Newton` ``` - -```{table} Example Table -name: tab-example -| Column 1 | Column 2 | -|----------|----------| -| A | B | -``` - 11. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows: @@ -118,14 +110,14 @@ name: tab-example 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. - ``` + ```{figure} figures/example.png + --- + width: 80% + align: center + name: fig-example + --- + Example figure. + ``` ``` 13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: From efbfe489f6f322169a417085806c2215252b45f4 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 26 Mar 2025 16:00:50 +0100 Subject: [PATCH 21/57] Update 009.md --- book/syntax_exercises/009.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index f526538..cb2fdd4 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -87,14 +87,14 @@ Refer to Equation {eq}`eq:Newton` 10. Similar methods can also be used to refer to a table. Start by creating a table by copying the code below. The identifier is defined using `:name:`. - ```md +```md ```{table} Example Table :name: tab-example | Column 1 | Column 2 | |----------|----------| | A | B | ``` - ``` +``` 11. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows: @@ -109,7 +109,7 @@ Refer to Equation {eq}`eq:Newton` 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 +```md ```{figure} figures/example.png --- width: 80% @@ -118,7 +118,7 @@ Refer to Equation {eq}`eq:Newton` --- Example figure. ``` - ``` +``` 13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: From 99e915ad0745751ba9474ccb44192a0854907d9e Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 26 Mar 2025 16:16:16 +0100 Subject: [PATCH 22/57] indent retry --- book/syntax_exercises/009.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index cb2fdd4..e7384e9 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -87,15 +87,22 @@ Refer to Equation {eq}`eq:Newton` 10. Similar methods can also be used to refer to a table. Start by creating a table by copying the code below. The identifier is defined using `:name:`. -```md + ```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 {numref}`Table {number} ` using `{numref}` and `{number}` as follows: @@ -103,6 +110,7 @@ Refer to Equation {eq}`eq:Newton` ```md {numref}`Table {number} ` ``` + ## Referencing a Figure @@ -110,14 +118,15 @@ Refer to Equation {eq}`eq:Newton` 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. - ``` +```{figure} figures/example.png +--- +width: 80% +align: center +name: fig-example +--- +Example figure. +``` +``` ``` 13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: From 537a5794175ce0dd3756c3f1929d176c32114f47 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 26 Mar 2025 16:19:11 +0100 Subject: [PATCH 23/57] indent retry 2 --- book/syntax_exercises/009.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index e7384e9..e612a30 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -95,7 +95,7 @@ Refer to Equation {eq}`eq:Newton` | A | B | ``` ``` - ``` + ```{table} Example Table :name: tab-example @@ -117,17 +117,17 @@ Refer to Equation {eq}`eq:Newton` 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. -``` -``` -``` + ```md + ```{figure} figures/example.png + --- + width: 80% + align: center + name: fig-example + --- + Example figure. + ``` + ``` + 13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: From 42f6aeebefae43505cfbb95ba299cea17cf9ac37 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 26 Mar 2025 16:29:10 +0100 Subject: [PATCH 24/57] indent retry 3 --- book/syntax_exercises/009.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index e612a30..cbc41b4 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -87,14 +87,14 @@ Refer to Equation {eq}`eq:Newton` 10. Similar methods can also be used to refer to a table. Start by creating a table by copying the code below. The identifier is defined using `:name:`. - ```md + ````md ```{table} Example Table :name: tab-example | Column 1 | Column 2 | |----------|----------| | A | B | ``` - ``` + ```` ```{table} Example Table @@ -117,7 +117,7 @@ Refer to Equation {eq}`eq:Newton` 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 + ````md ```{figure} figures/example.png --- width: 80% @@ -126,7 +126,7 @@ Refer to Equation {eq}`eq:Newton` --- Example figure. ``` - ``` + ```` 13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: From 09e0a7a2cee98fe2db3e94b6f500a96788ce1d0a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 08:37:07 +0100 Subject: [PATCH 25/57] add empty text --- book/syntax_exercises/009.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 8b23a46..4fb0e8f 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -24,6 +24,12 @@ 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) +``` 3. 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 using `{ref}` as shown in the example below. ```md From 601c7704f01963b3ac1b6a4f9728dfb64b5f63a8 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 08:37:21 +0100 Subject: [PATCH 26/57] update tip --- book/syntax_exercises/008.md | 4 ++-- book/syntax_exercises/009.md | 5 +++++ 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index 59c792b..c363da7 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -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/
.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/
` ) +```{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. `/
.png`). If your figure is in another directory, move upwards with `../` (e.g. `../..//
` ) ``` 6. To link and display an online figure, you can use the same `{figure}` directive. Just past in the : diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 4fb0e8f..6f8e9ef 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -30,6 +30,11 @@ If you leave the text part empty, the title of the chapter you're referring to w ```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. `/.md`). If the to be referenced chapter is in another directory, move upwards with `../` (e.g. `../..//` ) +``` + 3. 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 using `{ref}` as shown in the example below. ```md From aee353683e6c5f741dfa045b66573594d16bd579 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 08:41:31 +0100 Subject: [PATCH 27/57] Update book/syntax_exercises/009.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- book/syntax_exercises/009.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 64883c8..32d1ba6 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -163,8 +163,7 @@ Here is the [link to the template](https://teachbooks.github.io/template/). 16. Add a commit message. -17. To see you 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). - +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. From 551c3f0a3026151d1adb808e3566ade0884eb2b5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 08:41:51 +0100 Subject: [PATCH 28/57] Update 009.md --- book/syntax_exercises/009.md | 61 ++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 64883c8..ee85af1 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -51,25 +51,25 @@ Let's start with the most basic edit: add some text to a file and see that the w ``` 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. This will display: My favourite exercise was {ref}`exercise_1`. - ```md - My favourite exercise was {ref}`exercise_1`. - ``` +```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 <>. This will display: My favourite exercise was {ref}`the first one `. - ```md - My favourite exercise was {ref}`the first one `. - ``` +```md +My favourite exercise was {ref}`the first one `. +``` 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. This will display: My favourite exercise was [this one](exercise_1). - ```md - My favourite exercise was [this one](exercise_1). - ``` +```md +My favourite exercise was [this one](exercise_1). +``` ## Referencing an Equation @@ -77,11 +77,11 @@ This will display: My favourite exercise was {ref}`the first one `. 8. Now we will test our knowledge using an equation. Similar to the code below, create an equation using $$ and identify it using a label within the brackets. - ```md +```md - $$ F = m \cdot a$$ (eq:Newton) +$$ F = m \cdot a$$ (eq:Newton) - ``` +``` $$ F = m \cdot a$$ (eq:Newton) @@ -96,14 +96,14 @@ Refer to Equation {eq}`eq:Newton` 10. Similar methods can also be used to refer to a table. 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 | - ``` - ```` +````md +```{table} Example Table +:name: tab-example +| Column 1 | Column 2 | +|----------|----------| +| A | B | +``` +```` ```{table} Example Table @@ -126,16 +126,16 @@ Refer to Equation {eq}`eq:Newton` 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. - ``` - ```` +````md +```{figure} figures/example.png +--- +width: 80% +align: center +name: fig-example +--- +Example figure. +``` +```` 13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: @@ -175,3 +175,4 @@ 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? +``` \ No newline at end of file From b2b5a1a20a89647e9fccb1beeff2e9d96dad15eb Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 08:50:32 +0100 Subject: [PATCH 29/57] Additions --- book/syntax_exercises/009.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index d46c66e..a80e705 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -85,7 +85,7 @@ $$ 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 `` to achieve: Refer to Equation {eq}`eq:Newton`. +9. Refer to this equation by using `{eq}` and calling the identifier within the `` to achieve: Refer to Equation {eq}`eq:Newton`. This will automatically insert the number of the equation. You can add text as you did in exercise 6. Alternatively, you can use the default `[]()`: [Newton Equation](eq:Newton). ```md Refer to Equation {eq}`eq:Newton` @@ -113,14 +113,14 @@ Refer to Equation {eq}`eq:Newton` | A | B | ``` -11. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows: +11. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows. You can add text as you did in exercise 6. ```md {numref}`Table {number} ` ``` - +Or use the default `[]()`: [Reference to Example Table](tab-example) ## Referencing a Figure @@ -138,12 +138,15 @@ Example figure. ```` -13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: +13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows. You can add text as you did in exercise 6. ```md {numref}`Figure {number} ` ``` +Alternatively use `{ref}` to use the figure name instead of number, or use the default `[](
)`. + + ## Referencing a Link 14. Finally, let's reference a link, using the following syntax: From 026cd47dda2def0dcd309668a68b4bbe8cba9808 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 08:59:58 +0100 Subject: [PATCH 30/57] hide answers --- book/syntax_exercises/009.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index a80e705..76ca506 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -35,7 +35,7 @@ If you leave the text part empty, the title of the chapter you're referring to w 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. `/.md`). If the to be referenced chapter is in another directory, move upwards with `../` (e.g. `../..//` ) ``` -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. This code gives: [Jump to the next section](#referencing-an-equation) +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) @@ -49,7 +49,7 @@ If the chapter you're referring to is in different directory than your chapter, 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. This will display: My favourite exercise was {ref}`exercise_1`. +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`. @@ -57,14 +57,13 @@ 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 <>. -This will display: My favourite exercise was {ref}`the first one `. ```md My favourite exercise was {ref}`the first one `. ``` -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. This will display: My favourite exercise was [this 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 @@ -85,12 +84,13 @@ $$ 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 `` to achieve: Refer to Equation {eq}`eq:Newton`. This will automatically insert the number of the equation. You can add text as you did in exercise 6. Alternatively, you can use the default `[]()`: [Newton Equation](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 `[](). ## Referencing a Table @@ -113,14 +113,14 @@ Refer to Equation {eq}`eq:Newton` | A | B | ``` -11. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows. You can add text as you did in exercise 6. +11. Refer to the table like with custom text 'Table' and the number using `{numref}` and `{number}` as follows. You can add text as you did in exercise 6. ```md {numref}`Table {number} ` ``` -Or use the default `[](
)`: [Reference to Example Table](tab-example) +Or use the default `[](
)`. ## Referencing a Figure @@ -138,13 +138,13 @@ Example figure. ```` -13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows. You can add text as you did in exercise 6. +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} ` ``` -Alternatively use `{ref}` to use the figure name instead of number, or use the default `[](
)`. +Alternatively, you get an automatic text 'Fig.' and the number when using `` {numref}`` ``. Or use `{ref}` to use the figure name instead of number. Next to all of that you can use the default `[](
)`. ## Referencing a Link @@ -154,7 +154,7 @@ Alternatively use `{ref}` to use the figure name instead of number, or use the d ```md [Text to display](url) ``` -For example, you can use the code below to display: Here is the [link to the template](https://teachbooks.github.io/template/). +For example, you can use the code. ```md From 8f08bd1a82bbe7a2a9dd4ad0fb0d0903edc105ca Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 09:04:07 +0100 Subject: [PATCH 31/57] final changes --- book/syntax_exercises/009.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 76ca506..5a99762 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -90,7 +90,7 @@ $$ F = m \cdot a$$ (eq:Newton) Refer to Equation {eq}`eq:Newton` ``` -Alternatively, you can use the default `[](). +Alternatively, you can use the default `[]()`. ## Referencing a Table @@ -113,14 +113,14 @@ Alternatively, you can use the default `[](). | A | B | ``` -11. Refer to the table like with custom text 'Table' and the number using `{numref}` and `{number}` as follows. You can add text as you did in exercise 6. +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}`Table {number} ` +{numref}`My table {number} ` ``` -Or use the default `[](
)`. +Alternatively, you get an automatic text 'Table ' and the number when using `` {numref}`` ``. Or use `{ref}` to use the table name instead of number. Next to all of that you can use the default `[](
)`. ## Referencing a Figure From 89951c83064f9e8eee0b685e1b9b5c5f067841f8 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 09:08:29 +0100 Subject: [PATCH 32/57] fix --- book/_config.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 9a80602..875faaf 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -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://.io/" # 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://.io/" # 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) From 03a99e8738d78324ec8ffab99d854eda400c1c93 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 10:36:27 +0100 Subject: [PATCH 33/57] Create CITATION.cff --- CITATION.cff | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 CITATION.cff diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..aa8dac5 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,64 @@ +# This CITATION.cff file was generated with cffinit. +# Visit https://bit.ly/cffinit to generate yours today! + +cff-version: 1.2.0 +preferred-citation: + type: book + authors: #replace with your own name(s) if you use this template + - 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' + - given-names: Robert + family-names: Lanzafame + email: r.c.lanzafame@tudelft.nl + affiliation: TeachBooks + orcid: 'https://orcid.org/0000-0003-1958-9049' + - given-names: Julie + family-names: Kirsch + affiliation: Delft University of Technology + - given-names: Katia + family-names: Gatt + affiliation: Delft University of Technology + - given-names: Alex + family-names: Baudoin + affiliation: Delft University of Technology + - given-names: Isabel + family-names: Slingerland + affiliation: Delft University of Technology + - given-names: Dennis + family-names: den Ouden-van der Horst + email: D.denOuden-vanderHorst@tudelft.nl + affiliation: TeachBooks + orcid: 'https://orcid.org/0009-0002-2627-8169' + 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" From eaed6e27714afb86c601a3ccf3036cdf06e6a38c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 10:40:26 +0100 Subject: [PATCH 34/57] Update CITATION.cff --- CITATION.cff | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CITATION.cff b/CITATION.cff index aa8dac5..45b1dcc 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,9 +2,18 @@ # Visit https://bit.ly/cffinit to generate yours today! cff-version: 1.2.0 +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 Book, please cite it using these metadata." +title: "Source files TeachBooks Template" #replace with your own title when you use this template 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 From b9731fa28bb803482314effb6d137559446a14be Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 10:41:17 +0100 Subject: [PATCH 35/57] Update CITATION.cff --- CITATION.cff | 32 -------------------------------- 1 file changed, 32 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index 45b1dcc..9577d43 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -10,38 +10,6 @@ message: "If you use this Book, please cite it using these metadata." title: "Source files TeachBooks Template" #replace with your own title when you use this template 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' - - given-names: Robert - family-names: Lanzafame - email: r.c.lanzafame@tudelft.nl - affiliation: TeachBooks - orcid: 'https://orcid.org/0000-0003-1958-9049' - - given-names: Julie - family-names: Kirsch - affiliation: Delft University of Technology - - given-names: Katia - family-names: Gatt - affiliation: Delft University of Technology - - given-names: Alex - family-names: Baudoin - affiliation: Delft University of Technology - - given-names: Isabel - family-names: Slingerland - affiliation: Delft University of Technology - - given-names: Dennis - family-names: den Ouden-van der Horst - email: D.denOuden-vanderHorst@tudelft.nl - affiliation: TeachBooks - orcid: 'https://orcid.org/0009-0002-2627-8169' url: 'https://teachbooks.github.io/template/' # replace with your own URL (book website / publisher link) when you use this template identifiers: - type: url From ab986d24d374fb8c836246a8b20d22598fd7a372 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 10:42:33 +0100 Subject: [PATCH 36/57] Update CITATION.cff --- CITATION.cff | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CITATION.cff b/CITATION.cff index 9577d43..f7157b9 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -10,6 +10,16 @@ message: "If you use this Book, please cite it using these metadata." title: "Source files TeachBooks Template" #replace with your own title when you use this template 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 From 85e87a0ea685a73c3e776683756cd115ac7efce4 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 10:44:18 +0100 Subject: [PATCH 37/57] Update CITATION.cff --- CITATION.cff | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index f7157b9..a50a6ce 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,12 +2,7 @@ # Visit https://bit.ly/cffinit to generate yours today! cff-version: 1.2.0 -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 Book, please cite it using these metadata." -title: "Source files TeachBooks Template" #replace with your own title when you use this template preferred-citation: type: book authors: #replace with your own name(s) if you use this template From dc84935bc704933fd58c75f2893a6324934482b2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 10:53:29 +0100 Subject: [PATCH 38/57] Update CITATION.cff --- CITATION.cff | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index a50a6ce..78b2be6 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,13 +2,13 @@ # Visit https://bit.ly/cffinit to generate yours today! cff-version: 1.2.0 -message: "If you use this Book, please cite it using these metadata." +message: 'If you use this Book, 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/" + name: 'TeachBooks Development Team' + website: 'https://teachbooks.io/' # - given-names: Tom # name-particle: van # family-names: Woudenberg @@ -19,10 +19,10 @@ preferred-citation: 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 + 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 + 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, @@ -32,7 +32,7 @@ preferred-citation: keywords: # replace with your own keywords when you use this template - TeachBooks - Template - - Jupyter Book + - '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 @@ -43,4 +43,4 @@ preferred-citation: - 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" + name: 'TeachBooks Development Team' From 3f44ff75e24905b0169d8f28955c20dfc46ce932 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 11:51:26 +0100 Subject: [PATCH 39/57] Update CITATION.cff --- CITATION.cff | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index 78b2be6..1dd011c 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,7 +2,12 @@ # Visit https://bit.ly/cffinit to generate yours today! cff-version: 1.2.0 -message: 'If you use this Book, please cite it using these metadata.' +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 From 2d6c7d1efab1c249ca2a158d4da07f91b2ac1ebc Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 15:19:56 +0100 Subject: [PATCH 40/57] Create WAIVER --- WAIVER | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 WAIVER diff --git a/WAIVER b/WAIVER new file mode 100644 index 0000000..c679280 --- /dev/null +++ b/WAIVER @@ -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 From 400d4b041beba84ea322419ac675f160dc1947bf Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 31 Mar 2025 22:12:12 +0200 Subject: [PATCH 41/57] exercises 9,10,11 --- book/syntax_exercises/009.md | 182 +++++++---------------------------- book/syntax_exercises/010.md | 65 +++++++++++++ book/syntax_exercises/011.md | 180 ++++++++++++++++++++++++++++++++++ 3 files changed, 281 insertions(+), 146 deletions(-) create mode 100644 book/syntax_exercises/010.md create mode 100644 book/syntax_exercises/011.md diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 5a99762..cd60613 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -1,180 +1,70 @@ -# Exercise 9: Cross-referencing content +# Exercise 9: Use equations -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. +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 create internal references to other sections, equations, tables, figures, and links? +Can you format and reference equations correctly in your book? :::::: ```{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). +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). ``` -## Referencing a Chapter or Section +## Writing equations -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. +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 -[Text to display](path/to/file.md) +$$ F_{res} = m \cdot a $$ ``` -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. `/.md`). If the to be referenced chapter is in another directory, move upwards with `../` (e.g. `../..//` ) -``` - -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 `. -``` - - -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. +3. Now, add an inline equation by enclosing the equation with single dollar signs. Try this example: ```md -My favourite exercise was [this one](exercise_1). +The displacement can be found using the equation $s = v \cdot t$. ``` +## Formatting mathematical symbols -## Referencing an Equation - -8. Now we will test our knowledge using an equation. Similar to the code below, create an equation using $$ and identify it using a label within the brackets. +4. In this step we will experiment with different LaTeX symbols. Use the following table and test each example in your Markdown file: -```md +| Name | Script | +|---|---| +| Square root | `\sqrt{4}` | +| Power | `^{2x}` | +| Fraction | `\frac{2}{3}` | +| Subscript | `_{gem}` | +| Superscript | `^{N}` | +| Multiplication | `\cdot` | -$$ F = m \cdot a$$ (eq:Newton) +5. 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)` | - $$ F = m \cdot a$$ (eq:Newton) +6. Test your understanding by adding a new equation of your choice, ideally one that requires many LaTex symbols! -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. +7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -```md -Refer to Equation {eq}`eq:Newton` -``` +8. Add a commit message. -Alternatively, you can use the default `[]()`. +9. 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). -## Referencing a Table - -10. Similar methods can also be used to refer to a table. 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} ` -``` - -Alternatively, you get an automatic text 'Table ' and the number when using `` {numref}`` ``. Or use `{ref}` to use the table name instead of number. Next to all of that you can use the default `[](
)`. - -## 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} ` -``` - -Alternatively, you get an automatic text 'Fig.' and the number when using `` {numref}`` ``. Or use `{ref}` to use the figure name instead of number. Next to all of that you can use the default `[](
)`. - - -## 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. +10. 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? -``` \ No newline at end of file +- What is the difference between inline and block equations? +- How do you use LaTeX formatting for different mathematical symbols? + +``` + diff --git a/book/syntax_exercises/010.md b/book/syntax_exercises/010.md new file mode 100644 index 0000000..baa6312 --- /dev/null +++ b/book/syntax_exercises/010.md @@ -0,0 +1,65 @@ +# Exercise 10: Create tables + +In this exercise, you will learn how to create and format tables in your TeachBook using Markdown and reStructuredText. + +::::::{topic} Exercise objective +Can you correctly format tables and reference them within your book? +:::::: + +```{tip} +Tables help organize and present structured data clearly. JupyterBook supports Markdown tables and reStructuredText list-tables. +``` + +## 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. Try the following example: + +```md +| Column 1 | Column 2 | Column 3 | +|---|---|---| +| Data 1 | Data 2 | Data 3 | +| Data 4 | Data 5 | Data 6 | +``` + +## Creating Tables with reStructuredText + +3. You can also create tables using the `list-table` directive. The advantage of this method is that it allows referencing (refer to [Exercise 11](011.md)). Try the following example: + +````md +```{list-table} Sample Data Table +:header-rows: 1 +* - Category + - Value 1 + - Value 2 +* - Item A + - 10 + - 20 +* - Item B + - 15 + - 30 +``` +```` + +5. 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. + +6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +7. Add a commit message. + +8. 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). + +9. 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 `list-table` instead of a Markdown table? +- What syntax is required to define a `list-table`? +- How do you specify column headers in a `list-table`? +``` + diff --git a/book/syntax_exercises/011.md b/book/syntax_exercises/011.md new file mode 100644 index 0000000..352cd63 --- /dev/null +++ b/book/syntax_exercises/011.md @@ -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. `/.md`). If the to be referenced chapter is in another directory, move upwards with `../` (e.g. `../..//` ) +``` + +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 `. +``` + + +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. 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 `[]()`. + +## Referencing a Table + +10. Similar methods can also be used to refer to a table. 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} ` +``` + +Alternatively, you get an automatic text 'Table ' and the number when using `` {numref}`` ``. Or use `{ref}` to use the table name instead of number. Next to all of that you can use the default `[](
)`. + +## 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} ` +``` + +Alternatively, you get an automatic text 'Fig.' and the number when using `` {numref}`` ``. Or use `{ref}` to use the figure name instead of number. Next to all of that you can use the default `[](
)`. + + +## 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? +``` \ No newline at end of file From fd37d2146a364d44c528720041cf1610b79522e6 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 31 Mar 2025 22:12:49 +0200 Subject: [PATCH 42/57] Update _toc.yml --- book/_toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/_toc.yml b/book/_toc.yml index 91a0b9f..68bb676 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -21,6 +21,8 @@ parts: - 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: references.md - file: changelog.md - file: credits.md From b48d0e014e30ff7d2b13ec5eae0d92b7349f4d2d Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 31 Mar 2025 22:26:53 +0200 Subject: [PATCH 43/57] slight changes --- book/syntax_exercises/009.md | 2 +- book/syntax_exercises/010.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index cd60613..af3c4b0 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -3,7 +3,7 @@ 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 format and reference equations correctly in your book? +Can you write and format equations correctly in your book? :::::: ```{tip} diff --git a/book/syntax_exercises/010.md b/book/syntax_exercises/010.md index baa6312..ca7d5bd 100644 --- a/book/syntax_exercises/010.md +++ b/book/syntax_exercises/010.md @@ -1,9 +1,9 @@ # Exercise 10: Create tables -In this exercise, you will learn how to create and format tables in your TeachBook using Markdown and reStructuredText. +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 and reference them within your book? +Can you correctly format tables within your book? :::::: ```{tip} @@ -24,7 +24,7 @@ Tables help organize and present structured data clearly. JupyterBook supports M ## Creating Tables with reStructuredText -3. You can also create tables using the `list-table` directive. The advantage of this method is that it allows referencing (refer to [Exercise 11](011.md)). Try the following example: +3. You can also create tables using the `list-table` directive. The advantage of this method is that it allows referencing (refer to [Exercise 11](011.md)). Use the code below to try this out. ````md ```{list-table} Sample Data Table From 8449d845cadc1f577c4ec7d4408c4f2deb25cb32 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 1 Apr 2025 07:47:38 +0200 Subject: [PATCH 44/57] extend equations exercise --- book/syntax_exercises/009.md | 43 +++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index af3c4b0..ce51f6f 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -19,7 +19,29 @@ Using properly formatted equations makes mathematical expressions clearer and mo $$ F_{res} = m \cdot a $$ ``` -3. Now, add an inline equation by enclosing the equation with single dollar signs. Try this example: +```{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`. 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: + +````md +```{math} +v = a \cdot t +``` +```` + +6. Click on `preview` again. Note that these equations don't render. That's because the 'math directive' 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 @@ -28,7 +50,7 @@ The displacement can be found using the equation $s = v \cdot t$. ## Formatting mathematical symbols -4. In this step we will experiment with different LaTeX symbols. Use the following table and test each example in your Markdown file: +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 | @@ -40,7 +62,7 @@ The displacement can be found using the equation $s = v \cdot t$. | Superscript | `^{N}` | | Multiplication | `\cdot` | -5. Extend this exercise by trying more advanced mathematical expressions: +9. Extend this exercise by trying more advanced mathematical expressions: | Name | Script | |---|---| @@ -48,15 +70,15 @@ The displacement can be found using the equation $s = v \cdot t$. | Integral | `\int_a^b dx` | | Sine function | `\sin(x)` | -6. Test your understanding by adding a new equation of your choice, ideally one that requires many LaTex symbols! +10. Test your understanding by adding a new equation of your choice, ideally one that requires many LaTex symbols! -7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +11. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -8. Add a commit message. +12. Add a commit message. -9. 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). +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). -10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +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 @@ -64,7 +86,8 @@ The displacement can be found using the equation $s = v \cdot t$. 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 LaTeX formatting for different mathematical symbols? - +- 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? ``` From aa3b5ae20fa6ae53c4cd1198812f999f4b894988 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 1 Apr 2025 07:48:28 +0200 Subject: [PATCH 45/57] add reference to 11 --- book/syntax_exercises/009.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index ce51f6f..077984c 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -31,7 +31,7 @@ $$ E = m \ccdot c^2 $$ 4. Check whether the equations renders correctly by clicking `preview`. 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: +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 [Exercise 11](011.md)): ````md ```{math} From 2be556ab05e9c74d6367c44358d9eecc4430eba4 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 1 Apr 2025 08:05:12 +0200 Subject: [PATCH 46/57] Small edits to equations page --- book/syntax_exercises/009.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 077984c..a9adf32 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -29,7 +29,7 @@ The syntax used for creation equations is TeX, a markup language for math. It's $$ E = m \ccdot c^2 $$ ``` -4. Check whether the equations renders correctly by clicking `preview`. Note that all ill-formatted equation are indicated in red, i.e. $\red{\text{\ccdot}}$ +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 `.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 [Exercise 11](011.md)): @@ -39,7 +39,7 @@ v = a \cdot t ``` ```` -6. Click on `preview` again. Note that these equations don't render. That's because the 'math directive' is a MyST feature (an extension of markdown), which is not supported by the GitHub previewer that only support markdown. +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: From e070d55a8c683820f58e656517387e5535973d17 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 1 Apr 2025 08:06:14 +0200 Subject: [PATCH 47/57] extend table example --- book/syntax_exercises/010.md | 43 +++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/book/syntax_exercises/010.md b/book/syntax_exercises/010.md index ca7d5bd..dabcd37 100644 --- a/book/syntax_exercises/010.md +++ b/book/syntax_exercises/010.md @@ -7,13 +7,13 @@ Can you correctly format tables within your book? :::::: ```{tip} -Tables help organize and present structured data clearly. JupyterBook supports Markdown tables and reStructuredText list-tables. +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. Try the following example: +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 | @@ -22,9 +22,31 @@ Tables help organize and present structured data clearly. JupyterBook supports M | Data 4 | Data 5 | Data 6 | ``` -## Creating Tables with reStructuredText +```{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. You can also create tables using the `list-table` directive. The advantage of this method is that it allows referencing (refer to [Exercise 11](011.md)). Use the code below to try this out. +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 [Exercise 11](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 @@ -41,15 +63,15 @@ Tables help organize and present structured data clearly. JupyterBook supports M ``` ```` -5. 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. +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. -6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -7. Add a commit message. +8. Add a commit message. -8. 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). +9. 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). -9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. @@ -58,8 +80,7 @@ Tables help organize and present structured data clearly. JupyterBook supports M 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 `list-table` instead of a Markdown table? -- What syntax is required to define a `list-table`? +- When would you choose to use a `table` instead of just a Markdown table? - How do you specify column headers in a `list-table`? ``` From fae3f34381ede9f30d57f58855e16f9571d776e3 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 1 Apr 2025 08:08:55 +0200 Subject: [PATCH 48/57] add references on references page --- book/syntax_exercises/009.md | 2 +- book/syntax_exercises/010.md | 2 +- book/syntax_exercises/011.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index a9adf32..c47122d 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -31,7 +31,7 @@ $$ 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 [Exercise 11](011.md)): +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} diff --git a/book/syntax_exercises/010.md b/book/syntax_exercises/010.md index dabcd37..ff3e38a 100644 --- a/book/syntax_exercises/010.md +++ b/book/syntax_exercises/010.md @@ -30,7 +30,7 @@ The syntax to type a table is a bit cumbersome. You could make use of online too ## 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 [Exercise 11](011.md)) Try it with the following example: +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 diff --git a/book/syntax_exercises/011.md b/book/syntax_exercises/011.md index 352cd63..a40da80 100644 --- a/book/syntax_exercises/011.md +++ b/book/syntax_exercises/011.md @@ -73,7 +73,7 @@ My favourite exercise was [this one](exercise_1). ## Referencing an Equation -8. Now we will test our knowledge using an equation. Similar to the code below, create an equation using $$ and identify it using a label within the brackets. +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 @@ -94,7 +94,7 @@ 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. Start by creating a table by copying the code below. The identifier is defined using `:name:`. +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 From 1280861cdd85977f4241563b9807ef3db9eb0743 Mon Sep 17 00:00:00 2001 From: Katia Gatt <k.gatt@student.tudelft.nl> Date: Tue, 8 Apr 2025 17:12:09 +0200 Subject: [PATCH 49/57] chapter 12 --- book/_toc.yml | 1 + book/syntax_exercises/010.md | 6 +- book/syntax_exercises/012.md | 118 +++++++++++++++++++++++++++++++++++ 3 files changed, 122 insertions(+), 3 deletions(-) create mode 100644 book/syntax_exercises/012.md diff --git a/book/_toc.yml b/book/_toc.yml index 68bb676..23ac43c 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -23,6 +23,7 @@ parts: - 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 diff --git a/book/syntax_exercises/010.md b/book/syntax_exercises/010.md index ff3e38a..ccb14a0 100644 --- a/book/syntax_exercises/010.md +++ b/book/syntax_exercises/010.md @@ -67,11 +67,11 @@ The syntax to type a table is a bit cumbersome. You could make use of online too 8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -8. Add a commit message. +9. Add a commit message. -9. 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. 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. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md new file mode 100644 index 0000000..7b22783 --- /dev/null +++ b/book/syntax_exercises/012.md @@ -0,0 +1,118 @@ +# 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](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html). +``` + + +## 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 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: Custom vs. Fixed titles +Here’s a quick overview: + +| Fixed Title | Custom Title Allowed | +|----------------------|----------------------| +| `note` | `admonition` | +| `tip` | `dropdown` | +| `warning` | | +| `attention` | | +| `caution` | | +| `important` | | +| `seealso` | | +| `hint` | | +| `danger` | | +| `error` | | +``` + + + +9. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +10. Add a commit message. + +11. 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). + +12. 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`? +``` + + From ad32147ec8edc0423dc74b09df583f4495286ada Mon Sep 17 00:00:00 2001 From: Katia Gatt <k.gatt@student.tudelft.nl> Date: Wed, 9 Apr 2025 16:24:08 +0200 Subject: [PATCH 50/57] final changes --- book/syntax_exercises/012.md | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index 7b22783..2b60263 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -79,25 +79,14 @@ This content is hidden until the user clicks the title. ```` 8. Check your understanding with the summary table below. -```{admonition} Summary: Custom vs. Fixed titles +```{admonition} Summary: Fixed vs. Custom Title Admonitions Here’s a quick overview: -| Fixed Title | Custom Title Allowed | -|----------------------|----------------------| -| `note` | `admonition` | -| `tip` | `dropdown` | -| `warning` | | -| `attention` | | -| `caution` | | -| `important` | | -| `seealso` | | -| `hint` | | -| `danger` | | -| `error` | | +| Fixed Title Admonitions | Custom Title Admonitions | +|------------------------------------------------------------------|-------------------------------| +| `note`, `tip`, `warning`, `attention`, `caution`, `important`, `seealso`, `hint`, `danger`, `error` | `admonition`, `dropdown` | ``` - - 9. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. 10. Add a commit message. From eb28a9f1de62be2167ad2cb71a18e816656fb779 Mon Sep 17 00:00:00 2001 From: Katia Gatt <k.gatt@student.tudelft.nl> Date: Sun, 13 Apr 2025 17:29:02 +0200 Subject: [PATCH 51/57] Update 012.md --- book/syntax_exercises/012.md | 132 +++++++++++++++++++++++++++++++++-- 1 file changed, 126 insertions(+), 6 deletions(-) diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index 2b60263..59b195d 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -49,7 +49,7 @@ Important: Save your work frequently. - `danger` -## Custom titles for admonitions +## Custom titles & styles for admonitions 5. Some admonitions allow you to **specify your own title**. Try the `admonition` directive: @@ -59,7 +59,6 @@ You can customise the title of this block using the `admonition` directive. ``` ```` - 6. Similarly, you can customise titles for `dropdown` admonitions: ````md @@ -77,6 +76,7 @@ This content is hidden until the user clicks the title. 3. Preview the changes. ``` ```` + 8. Check your understanding with the summary table below. ```{admonition} Summary: Fixed vs. Custom Title Admonitions @@ -87,13 +87,132 @@ Here’s a quick overview: | `note`, `tip`, `warning`, `attention`, `caution`, `important`, `seealso`, `hint`, `danger`, `error` | `admonition`, `dropdown` | ``` -9. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +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: -10. Add a commit message. +````md +```{admonition} Pro tip! +:class: tip -11. 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). +You can apply styles using the `:class:` option. +``` +```` -12. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +````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`admonitions. 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 built-in Sphinx colour classes. To do so, it is necessary to follow the installation process outlined below: + +**Step A: Install the Package** + +Install the `sphinx-named-colors` package using `pip`: + +``` +pip install sphinx-named-colors +``` + +**Step B: Add to `requirements.txt`** + +Ensure that the package is included in your project's `requirements.txt` to track the dependency: + +``` +sphinx-named-colors +``` + +**Step C: Enable in `_config.yml`** + +In your `_config.yml` file, add the extension to the list of Sphinx extra extensions: + +``` +sphinx: + extra_extensions: + . + . + . + - sphinx_named_colors + . + . + . +``` + +14. Once the installation is done, we can experiment with custom-coloured admonitions! Go ahead and look at the available [Sphinx Named Colours](https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html#admonitions), 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 +:class: darkred + +This is a custom coloured admonition using `:class: darkred`. +``` +```` + +16. When using the above method, a new class is introduced: `no-title`. This suppresses printing of the title bar, even if the title is given. Try this out by adding this class to the above code. + +17. 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 + +This is a green-styled custom admonition. +``` +```` + +18. For the second method using named colour admonitions, a new class is also introduced: `show-bar`. This allows titleless admonitions, which forces printing of the title bar. Try this out using the code above with an omitted title, and this added class. + +19. For both methods, you can also combine classes here, for example, `:class: darkblue dropdown` to make it collapsible and coloured. Test this out, building on the above examples. + + +20. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +21. Add a commit message. + +22. 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). + +23. 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 @@ -102,6 +221,7 @@ 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? ``` From b4f919d50ad20e289bdabf2f0c175decfb8cbebd Mon Sep 17 00:00:00 2001 From: Katia Gatt <k.gatt@student.tudelft.nl> Date: Sun, 13 Apr 2025 17:47:26 +0200 Subject: [PATCH 52/57] small update 012.md --- book/syntax_exercises/012.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index 59b195d..2a11345 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -115,7 +115,7 @@ 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`admonitions. Try customize admonitions yourself, using different classes from the table. +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 | @@ -177,7 +177,7 @@ sphinx: . ``` -14. Once the installation is done, we can experiment with custom-coloured admonitions! Go ahead and look at the available [Sphinx Named Colours](https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html#admonitions), and pick a desired colour. +14. Once the installation is done, 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: @@ -201,7 +201,7 @@ This is a green-styled custom admonition. ``` ```` -18. For the second method using named colour admonitions, a new class is also introduced: `show-bar`. This allows titleless admonitions, which forces printing of the title bar. Try this out using the code above with an omitted title, and this added class. +18. For the second method using named colour admonitions, a new class is also introduced for titleless admonitions: `show-bar`. This forces printing of the title bar. If a title is given, the title will be printed too and adding the class `show-bar` is redundant. Try this out using the code above with an omitted title, and this added class. 19. For both methods, you can also combine classes here, for example, `:class: darkblue dropdown` to make it collapsible and coloured. Test this out, building on the above examples. From d795f3db0fadc739c92a2193f7f667824d4fcc30 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Mon, 14 Apr 2025 09:18:50 +0200 Subject: [PATCH 53/57] Small changes Tom --- book/syntax_exercises/012.md | 31 ++++++++++--------------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index 2a11345..b9a7d45 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -143,17 +143,9 @@ 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 built-in Sphinx colour classes. To do so, it is necessary to follow the installation process outlined below: +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: -**Step A: Install the Package** - -Install the `sphinx-named-colors` package using `pip`: - -``` -pip install sphinx-named-colors -``` - -**Step B: Add to `requirements.txt`** +**Step A: Add to `requirements.txt`** Ensure that the package is included in your project's `requirements.txt` to track the dependency: @@ -161,11 +153,11 @@ Ensure that the package is included in your project's `requirements.txt` to trac sphinx-named-colors ``` -**Step C: Enable in `_config.yml`** +**Step B: Enable in `_config.yml`** In your `_config.yml` file, add the extension to the list of Sphinx extra extensions: -``` +```md sphinx: extra_extensions: . @@ -177,7 +169,7 @@ sphinx: . ``` -14. Once the installation is done, 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. +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: @@ -201,18 +193,15 @@ This is a green-styled custom admonition. ``` ```` -18. For the second method using named colour admonitions, a new class is also introduced for titleless admonitions: `show-bar`. This forces printing of the title bar. If a title is given, the title will be printed too and adding the class `show-bar` is redundant. Try this out using the code above with an omitted title, and this added class. +18. 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! -19. For both methods, you can also combine classes here, for example, `:class: darkblue dropdown` to make it collapsible and coloured. Test this out, building on the above examples. +19. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +20. Add a commit message. -20. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +21. 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. Add a commit message. - -22. 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). - -23. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +22. 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 From 5dcd816588a6766885b1ee737eecbee5d64a6556 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Mon, 14 Apr 2025 09:23:04 +0200 Subject: [PATCH 54/57] Update 012.md --- book/syntax_exercises/012.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index b9a7d45..bb0b7f3 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -7,7 +7,7 @@ Can you structure your content with different types of admonitions and understan :::::: ```{tip} -Admonitions help to guide readers' attention and make your book more accessible. Full documentation is available [here](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html). +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). ``` From df988b1a6d65672e4ed5f3a7ba9c31e8fc36af9f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Mon, 14 Apr 2025 09:27:08 +0200 Subject: [PATCH 55/57] another small change --- book/syntax_exercises/012.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index bb0b7f3..9e969c9 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -147,15 +147,21 @@ This content is both highlighted as important and collapsible. **Step A: Add to `requirements.txt`** -Ensure that the package is included in your project's `requirements.txt` to track the dependency: +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, add the extension to the list of Sphinx extra extensions: +In your `_config.yml` file (in the `book/` subdirectory of your repository), add the extension to the list of Sphinx extra extensions so that it's included in the building of your book: ```md sphinx: @@ -174,34 +180,32 @@ sphinx: 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 +```{admonition} Custom Colour Example 1 :class: darkred This is a custom coloured admonition using `:class: darkred`. ``` ```` -16. When using the above method, a new class is introduced: `no-title`. This suppresses printing of the title bar, even if the title is given. Try this out by adding this class to the above code. - -17. 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: +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 +```{darkgreen} Optional Title with custom coluor example 2 This is a green-styled custom admonition. ``` ```` -18. 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! +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! -19. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +18. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -20. Add a commit message. +19. Add a commit message. -21. 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). +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). -22. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +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 From 160227f991e84a371ca8177df837ca107eb36067 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Mon, 14 Apr 2025 09:29:07 +0200 Subject: [PATCH 56/57] Update 012.md --- book/syntax_exercises/012.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index 9e969c9..f64f920 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -143,7 +143,7 @@ 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: +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`** From 204b50c769bfbc65c039a1aed3cea5fe5bc87223 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Mon, 14 Apr 2025 09:42:24 +0200 Subject: [PATCH 57/57] Update 012.md --- book/syntax_exercises/012.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index f64f920..6f80704 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -161,7 +161,7 @@ sphinx-named-colors **Step B: Enable in `_config.yml`** -In your `_config.yml` file (in the `book/` subdirectory of your repository), add the extension to the list of Sphinx extra extensions so that it's included in the building of your book: +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: