Tables in Markdown¶

When writing documentation in Markdown using Sphinx and MyST-Parser you can use the standard Markdown syntax or MyST-Parser directives table, csv-table and list-table.

Standard syntax¶

MyST-Parser supports the usual table syntax of the standard Github Flavoured Markdown. It is the simplest and more readable table syntax in Markdown:

| Header One   | Header Two     | Header Three    |
| ------------ | -------------- | --------------- |
| Nulla 1      | Lacus 2        | Hendrerit 3     |
| Dignissim 11 | Morbi 12       | Pellentesque 13 |
| Donec sit 21 | Ullamcorper 22 | Quis 23         |
| Phasellus 31 | Ante 32        | Tempus 33       |

Header One	Header Two	Header Three
Nulla 1	Lacus 2	Hendrerit 3
Dignissim 11	Morbi 12	Pellentesque 13
Donec sit 21	Ullamcorper 22	Quis 23
Phasellus 31	Ante 32	Tempus 33

Column alignment¶

Cells in a column can be aligned using the colon character (:):

Align to the left by adding a : to the beggining of the hyphens.
Align to the center by adding a : to the beggining and to the end of the hyphens.
Align to the right by adding a : to the end of the hyphens.

An example table with alignment:

| Header One   | Header Two     | Header Three    |
| :----------- | :------------: | --------------: |
| Nulla 1      | Lacus 2        | Hendrerit 3     |
| Dignissim 11 | Morbi 12       | Pellentesque 13 |
| Donec sit 21 | Ullamcorper 22 | Quis 23         |
| Phasellus 31 | Ante 32        | Tempus 33       |

Header One	Header Two	Header Three
Nulla 1	Lacus 2	Hendrerit 3
Dignissim 11	Morbi 12	Pellentesque 13
Donec sit 21	Ullamcorper 22	Quis 23
Phasellus 31	Ante 32	Tempus 33

`table` directive¶

MyST-Parser’s table directive provides more style customization and can be used to create tables with caption:

:::{table} Table caption
:width: 65
:widths: auto
:align: center

| Header One   | Header Two     | Header Three    |
| :----------- | :------------: | --------------: |
| Nulla 1      | Lacus 2        | Hendrerit 3     |
| Dignissim 11 | Morbi 12       | Pellentesque 13 |
| Donec sit 21 | Ullamcorper 22 | Quis 23         |
| Phasellus 31 | Ante 32        | Tempus 33       |
:::

Table caption¶
Header One	Header Two	Header Three
Nulla 1	Lacus 2	Hendrerit 3
Dignissim 11	Morbi 12	Pellentesque 13
Donec sit 21	Ullamcorper 22	Quis 23
Phasellus 31	Ante 32	Tempus 33

`csv-table` directive¶

The csv-table directive creates a table from Comma-Separated-Values data. See the complete documentation of the csv-table directive in the MyST-Parser docs. Here is an example based on the data from the previous table:

:::{csv-table} Table caption
:header: >
:   "Header One", "Header Two", "Header Three"
:width: 65%
:widths: auto
:align: center

"Nulla 1", "Lacus 2", "Hendrerit 3"
"Dignissim 11", "Morbi 12", "Pellentesque 13"
"Donec sit 21", "Ullamcorper 22", "Quis 23"
"Phasellus 31", "Ante 32", "Tempus 33"
:::

Table caption¶
Header One	Header Two	Header Three

Nulla 1	Lacus 2	Hendrerit 3
Dignissim 11	Morbi 12	Pellentesque 13
Donec sit 21	Ullamcorper 22	Quis 23
Phasellus 31	Ante 32	Tempus 33

`list-table` directive¶

The list-table directive (MyST-Parser docs on list-table) is used to create a table from data in a uniform two-level bullet list. “Uniform” means that each sublist (second-level list) must contain the same number of list items.

Here below is an example of a list-table:

:::{list-table} Board games
:widths: 20 15 65
:header-rows: 1

*   - Name
    - Number of players
    - Description
*   - Catan
    - 3 to 4
    - Players take on the roles of settlers, each attempting to build and
     develop holdings while trading and acquiring resources. Players gain
     victory points as their settlements grow and the first to reach a set
     number of victory points, typically 10, wins.
*   - Ticket to Ride
    - 2 to 5
    - Players collect and play train car cards to claim train routes across the
     map. Points are earned based on the length of the claimed routes, whoever
     completes the longest continuous railway, and whether the player can
     connect distant cities which are determined by drawing ticket cards.
*   - Chess
    - 2
    - An abstract strategy game that involves no hidden information and no
     elements of chance. Today, chess is one of the world's most popular games
     played by millions of people worldwide.
:::

Board games¶
Name	Number of players	Description
Catan	3 to 4	Players take on the roles of settlers, each attempting to build and develop holdings while trading and acquiring resources. Players gain victory points as their settlements grow and the first to reach a set number of victory points, typically 10, wins.
Ticket to Ride	2 to 5	Players collect and play train car cards to claim train routes across the map. Points are earned based on the length of the claimed routes, whoever completes the longest continuous railway, and whether the player can connect distant cities which are determined by drawing ticket cards.
Chess	2	An abstract strategy game that involves no hidden information and no elements of chance. Today, chess is one of the world’s most popular games played by millions of people worldwide.

A wide table example¶

This is an extract of the first 10 rows of the table of the World’s 100 most threatened species, taken from Wikipedia.

The World’s 100 most threatened species¶
Species	Common name	Type	Location(s)	Estimated population	Threats
Abies beshanzuensis	Baishan fir	Plant (Tree)	Baishanzu Mountain, Zhejiang, China	Three mature individuals	agriculture fire
Actinote zikani		Insect (butterfly)	Near São Paulo, Atlantic forest, Brazil	Unknown	habitat loss from human expansion
Aipysurus foliosquama	Leaf scaled sea-snake	Reptile	Ashmore Reef and Hibernia Reef, Timor Sea	Unknown	unknown—probably degradation of coral reef habitat
Amanipodagrion gilliesi	Amani flatwing	Insect (damselfly)	Amani-Sigi Forest, Usamabara Mountains, Tanzania	< 500 individuals	population pressure and water pollution
Antisolabis seychellensis		Insect	Morne Blanc, Mahé island, Seychelles	Unknown	invasive species climate change
Antilophia bokermanni	Araripe manakin	Bird	Chapado do Araripe, South Ceará, Brazil	779 individuals	recreational facilities water diversion
Aphanius transgrediens	Aci Göl toothcarp	Fish	south-eastern shore of former Lake Aci, Turkey	few hundred pairs	competition and predation by Gambusia road construction
Ardea insignis	White bellied heron	Bird	Bhutan, North East India and Myanmar	70–400 individuals	hydropower development
Ardeotis nigriceps	Great Indian bustard	Bird	Rajasthan, Gujarat, Maharashtra, Andhra Pradesh, Karnataka and Madhya, India	50–249 mature individuals	agricultural development energy transmission lines
Astrochelys yniphora	Ploughshare tortoise	Reptile	Baly Bay region, northwestern Madagascar	440–770	illegal collection for international pet trade