From 400d4b041beba84ea322419ac675f160dc1947bf Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 31 Mar 2025 22:12:12 +0200 Subject: [PATCH 1/8] 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 2/8] 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 3/8] 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 4/8] 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 5/8] 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 6/8] 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 7/8] 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 8/8] 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