mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-30 18:24:35 +01:00
186 lines
5.9 KiB
Markdown
186 lines
5.9 KiB
Markdown
---
|
||
template: overrides/main.html
|
||
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://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/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://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/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
|