From e070d55a8c683820f58e656517387e5535973d17 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 1 Apr 2025 08:06:14 +0200 Subject: [PATCH] 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 `.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`? ```