mkdocs-material/docs/reference/data-tables.md

icon
material/table-edit

Data tables

Material for MkDocs defines default styles for data tables – an excellent way of rendering tabular data in project documentation. Furthermore, customizations like sortable tables can be achieved with a third-party library and some additional JavaScript.

Configuration

This configuration enables Markdown table support, which should normally be enabled by default, but to be sure, add the following lines to mkdocs.yml:

markdown_extensions:
  - tables

See additional configuration options:

• Tables

Usage

Data tables can be used at any position in your project documentation and can contain arbitrary Markdown, including inline code blocks, as well as icons and emojis:

| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

Method	Description
GET	:material-check: Fetch resource
PUT	:material-check-all: Update resource
DELETE	:material-close: Delete resource

Column alignment

If you want to align a specific column to the left, center or right, you can use the regular Markdown syntax placing : characters at the beginning and/or end of the divider.

=== "Left"

``` markdown hl_lines="2" title="Data table, columns aligned to left"
| Method      | Description                          |
| :---------- | :----------------------------------- |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |
```

<div class="result" markdown>

| Method      | Description                          |
| :---------- | :----------------------------------- |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

</div>

=== "Center"

``` markdown hl_lines="2" title="Data table, columns centered"
| Method      | Description                          |
| :---------: | :----------------------------------: |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |
```

<div class="result" markdown>

| Method      | Description                          |
| :---------: | :----------------------------------: |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

</div>

=== "Right"

``` markdown hl_lines="2" title="Data table, columns aligned to right"
| Method      | Description                          |
| ----------: | -----------------------------------: |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |
```

<div class="result" markdown>

| Method      | Description                          |
| ----------: | -----------------------------------: |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

</div>

Customization

Sortable tables

If you want to make data tables sortable, you can add tablesort, which is natively integrated with Material for MkDocs and will also work with instant loading via additional JavaScript:

=== ":octicons-file-code-16: docs/javascripts/tablesort.js"

``` js
document$.subscribe(function() {
  var tables = document.querySelectorAll("article table:not([class])")
  tables.forEach(function(table) {
    new Tablesort(table)
  })
})
```

=== ":octicons-file-code-16: mkdocs.yml"

``` yaml
extra_javascript:
  - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
  - javascripts/tablesort.js
```

After applying the customization, data tables can be sorted by clicking on a column:

| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |

Method	Description
GET	:material-check: Fetch resource
PUT	:material-check-all: Update resource
DELETE	:material-close: Delete resource

Note that tablesort provides alternative comparison implementations like numbers, filesizes, dates and month names. See the [tablesort documentation] tablesort for more information.

Import table from file

:octicons-cpu-24: Plugin

You can also import data from a CSV or Excel file using the plugin mkdocs-table-reader-plugin.

First, you will need to install it with pip:

pip install mkdocs-table-reader-plugin

Then extend the mkdocs.yml file like this:

plugins:
  - table-reader

Then, it is a simple process to import the data in to the Markdown files.

=== "Import data from :fontawesome-solid-file-csv: CSV file"

Let's use a :fontawesome-solid-file-csv: CSV in the local directory. The file may look like this:

```csv title="./data.csv"
col1,col2,col3
r1c1,r1c2,r1c3
r2c1,r2c2,r2c3
r3c1,r3c2,r3c3
```

You can then add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:

```md title="./markdown.md"
...

{{ read_csv('./data.csv') }}

...
```

<div class="result" markdown>

...

col1|col2|col3
----|----|----
r1c1|r1c2|r1c3
r2c1|r2c2|r2c3
r3c1|r3c2|r3c3

...

</div>

=== "Import data from :fontawesome-solid-file-excel: Excel file"

Let's use an :fontawesome-solid-file-excel: Excel file in the local directory. The file may look like this:

![][excel-file]{width="300px"}

[excel-file]: https://i.stack.imgur.com/f32ks.png

And you can add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:

```md title="./markdown.md"
...

{{ read_excel('./Book1.xlsx', engine='openpyxl') }}

...
```

<div class="result" markdown>

It will then return a result like this:

col1|col2|col3
----|----|----
r1c1|r1c2|r1c3
r2c1|r2c2|r2c3
r3c1|r3c2|r3c3

</div>

!!! warning "Warning"
    
    You may receive an error if you use `engine='openpyxl'`.

    If this happens, you can resolve it by installing it using `pip`:

    ```sh
    pip install openpyxl
    ```

    Read more here: [pandas.read_excel][pandas-read_excel-engine]
    
    [pandas-read_excel-engine]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=enginestr%2C%20default%20None

!!! tip "Pro Tip: Multiple Sheets"

    If your Excel file contains multiple sheets, you may want to extend the function by adding the `sheet_name` parameter.

    It would look like this:

    ```md title="./markdown.md"
    ...

    {{ read_excel('./Book1.xlsx', engine='openpyxl', sheet_name="Sheet1") }}

    ...
    ```

    By default, Pandas will grab the first sheet in the workbook.

    Read more here: [pandas.read_excel][pandas-read_excel-sheet_name]
    
    [pandas-read_excel-sheet_name]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=sheet_namestr%2C%20int%2C%20list%2C%20or%20None%2C%20default%200

=== "Import data from other file types"

The plugin [`mkdocs-table-reader-plugin`][table-reader-docs] also provides readers for other formats:

<div class="mdx-columns" markdown>

- [`read_csv`][table-reader-read_csv]
- [`read_fwf`][table-reader-read_fwf]
- [`read_yaml`][table-reader-read_yaml]
- [`read_table`][table-reader-read_table]
- [`read_json`][table-reader-read_json]
- [`read_excel`][table-reader-read_excel]
- [`read_raw`][table-reader-read_raw]

</div>

You can read more on their Docs website: [mkdocs-table-reader-plugin][table-reader-docs]