Create tables

Create tables#

In this exercise, we will explore how to create and format tables in your TeachBook using Markdown and reStructuredText.

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 are available too. Try the following example:

| 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 if you don’t want to do all the typing yourself. This tool even allows copy pasting from Microsoft Excel!

  1. 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#

  1. You can also use the table directive to create tables with additional formatting options: captions and layout options. Furthermore, this method allows referencing (refer to Cross-referencing content) Try it with the following example:

```{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  |
```

  1. 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.

  2. You can also create tables using the list-table directive. Use the code below to try this out.

```{list-table} Sample Data Table
:header-rows: 1
* - Category
  - Value 1
  - Value 2
* - Item A
  - 10
  - 20
* - Item B
  - 15
  - 30
```

  1. 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.

  2. When you are ready, commit your changes to the repository by clicking on the green Commit changes button.

  3. Add a commit message.

  4. To see your changes, go to 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).

  5. Do you see your change? If you don’t see it click CTRL+F5/Control+F5to refresh the page.

Check your understanding

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?

Contents