# 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`?  
```