1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-25 22:04:52 +01:00
mkdocs-material/docs/reference/data-tables.md

192 lines
6.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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].
[sortable tables]: #sortable-tables
[additional JavaScript]: ../customization.md#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`:
``` yaml
markdown_extensions:
- tables
```
See additional configuration options:
- [Tables]
[Tables]: ../setup/extensions/python-markdown.md#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]:
``` markdown title="Data table"
| 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>
[icons and emojis]: icons-emojis.md
### 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>
[regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables
## 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:
``` markdown title="Data table, columns sortable"
| 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>
Note that [tablesort] provides alternative comparison implementations like
numbers, filesizes, dates and month names. See the [tablesort documentation]
[tablesort] for more information.
<script src="https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js"></script>
<script>
var tables = document.querySelectorAll("article table")
new Tablesort(tables.item(tables.length - 1));
</script>
[tablesort]: http://tristen.ca/tablesort/demo/
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
### Import table from file
The plugin [mkdocs-table-reader-plugin][table-reader-docs] allows you to
import data from a CSV or Excel file.
[table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/