数据表格

Material for MkDocs 定义了数据表格的默认样式，这是在项目文档中呈现表格数据的绝佳方式。此外，可以通过第三方库和一些额外的 JavaScript 实现自定义，例如[可排序的表格]。

配置

要启用 Markdown 表格支持，通常应默认启用，但为了确保，请将以下行添加到mkdocs.yml文件中：

markdown_extensions:
  - tables

查看额外的配置选项：

Tables

使用方法

数据表格可以在项目文档的任何位置使用，可以包含任意的 Markdown 内容，包括内联代码块，以及图标和表情：

数据表格

| Method   | Description                   |
| -------- | ----------------------------- |
| `GET`    | :material-check: 获取资源     |
| `PUT`    | :material-check-all: 更新资源 |
| `DELETE` | :material-close: 删除资源     |

Method	Description
`GET`	获取资源
`PUT`	更新资源
`DELETE`	删除资源

列对齐

如果要将特定列对齐到“左侧”、“中间”或“右侧”，可以使用[常规的 Markdown 语法]，在分隔线的开头和/或结尾放置:字符。

左对齐居中对齐右对齐

数据表格，列左对齐

| Method      | Description                          |
| :---------- | :----------------------------------- |
| `GET`       | :material-check:     获取资源        |
| `PUT`       | :material-check-all: 更新资源       |
| `DELETE`    | :material-close:     删除资源       |

Method	Description
`GET`	获取资源
`PUT`	更新资源
`DELETE`	删除资源

数据表格，列居中对齐

| Method      | Description                          |
| :---------: | :----------------------------------: |
| `GET`       | :material-check:     获取资源        |
| `PUT`       | :material-check-all: 更新资源       |
| `DELETE`    | :material-close:     删除资源       |

Method	Description
`GET`	获取资源
`PUT`	更新资源
`DELETE`	删除资源

数据表格，列右对齐

| Method      | Description                          |
| ----------: | -----------------------------------: |
| `GET`       | :material-check:     获取资源        |
| `PUT`       | :material-check-all: 更新资源       |
| `DELETE`    | :material-close:     删除资源       |

Method	Description
`GET`	获取资源
`PUT`	更新资源
`DELETE`	删除资源

自定义

可排序的表格

如果要使数据表格可排序，可以添加tablesort，它与 Material for MkDocs 原生集成，并且还可以通过[额外的 JavaScript]与即时加载一起使用：

docs/javascripts/tablesort.js mkdocs.yml

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

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

应用自定义后，可以通过单击列来对数据表格进行排序：

数据表格，可排序的列

| Method   | Description                   |
| -------- | ----------------------------- |
| `GET`    | :material-check: 获取资源     |
| `PUT`    | :material-check-all: 更新资源 |
| `DELETE` | :material-close: 删除资源     |

Method	Description
`GET`	获取资源
`PUT`	更新资源
`DELETE`	删除资源

请注意，tablesort提供了替代的比较实现，例如数字、文件大小、日期和月份名称。有关更多信息，请参阅tablesort 文档。

从文件导入表格

插件

您还可以使用插件mkdocs-table-reader-plugin从 CSV 或 Excel 文件导入数据。

首先，您需要使用pip安装它：

pip install mkdocs-table-reader-plugin

然后在mkdocs.yml文件中进行扩展：

plugins:
  - table-reader

然后，将数据导入到 Markdown 文件中非常简单。

从 CSV 文件导入数据从 Excel 文件导入数据从其他文件类型导入数据

让我们使用本地目录中的 CSV 文件。文件可能如下所示：

./data.csv

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

您可以像这样将其添加到 Markdown 页面中：

./markdown.md

...

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

...

...

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

...

让我们使用本地目录中的 Excel 文件。文件可能如下所示：

然后，您可以像这样将其添加到 Markdown 页面中：

./markdown.md

...

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

...

它将返回如下结果：

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

警告

如果使用engine='openpyxl'时出现错误，您可能会收到错误提示。

如果发生这种情况，您可以使用pip安装它来解决：

pip install openpyxl

在此处阅读更多信息：pandas.read_excel

专业提示：多个工作表

如果您的Excel文件包含多个工作表，您可以通过添加sheet_name参数来扩展函数。

它将如下所示：

./markdown.md

...

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

...

默认情况下，Pandas将获取工作簿中的第一个工作表。

在此处阅读更多信息：pandas.read_excel

插件mkdocs-table-reader-plugin还提供了其他格式的读取器：

您可以在其文档网站上阅读更多信息：mkdocs-table-reader-plugin