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