1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00

Added documentation for data tables

This commit is contained in:
squidfunk 2020-08-04 22:22:47 +02:00
parent d6738cad0d
commit 0ccbcb6edb
10 changed files with 217 additions and 9 deletions

View File

@ -0,0 +1,171 @@
---
template: overrides/main.html
---
# 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][1] can be achieved with a third-party library and some
[additional JavaScript][2].
[1]: #sortable-tables
[2]: ../customization.md#additional-javascript
## Configuration
None.
## Usage
### Using data tables
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][3].
_Example_:
``` markdown
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```
_Result_:
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
[3]: 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][4] placing `:` characters at the beginning
and/or end of the divider.
=== "Left"
_Example_:
``` markdown hl_lines="2"
| Method | Description |
| :---------- | :----------------------------------- |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```
_Result_:
| Method | Description |
| :---------- | :----------------------------------- |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
=== "Center"
_Example_:
``` markdown hl_lines="2"
| Method | Description |
| :---------: | :----------------------------------: |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```
_Result_:
| Method | Description |
| :---------: | :----------------------------------: |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
=== "Right"
_Example_:
``` markdown hl_lines="2"
| Method | Description |
| ----------: | -----------------------------------: |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```
_Result_:
| Method | Description |
| ----------: | -----------------------------------: |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
[4]: https://www.markdownguide.org/extended-syntax/#tables
## Customization
### Sortable tables
If you want to make data tables sortable, you can add [tablesort][5] via
[additional JavaScript][2], which is natively integrated with Material for
MkDocs and will also work with [instant loading][6]:
=== "docs/javascripts/tables.js"
``` js
app.location$.subscribe(function() {
var tables = document.querySelectorAll("article table")
tables.forEach(function(table) {
new Tablesort(table)
})
})
```
=== "mkdocs.yml"
``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
- javascripts/tables.js
```
_Note that [tablesort][5] provides alternative comparison implementations like
numbers, dates, filesizes and month names. See the official documentation for
more information._
_Example_:
``` markdown
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```
_Result_:
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
<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>
[5]: http://tristen.ca/tablesort/demo/
[6]: ../setup/setting-up-navigation.md#instant-loading

View File

@ -34,7 +34,7 @@ Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
the JavaScript runtime need to be included, which can be done with [additional
JavaScript][8]:
=== "docs/javascript/config.js"
=== "docs/javascripts/config.js"
``` js
window.MathJax = {

View File

@ -5,8 +5,8 @@
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.c3dc8c49.min.js.map",
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.8e2cddea.min.js",
"assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.8e2cddea.min.js.map",
"assets/stylesheets/main.css": "assets/stylesheets/main.e584d62f.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.e584d62f.min.css.map",
"assets/stylesheets/main.css": "assets/stylesheets/main.6fb40bf7.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.6fb40bf7.min.css.map",
"assets/stylesheets/overrides.css": "assets/stylesheets/overrides.011ebae6.min.css",
"assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.011ebae6.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.cef4c379.min.css",

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

View File

@ -41,7 +41,7 @@
{% endif %}
{% endblock %}
{% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.e584d62f.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.6fb40bf7.min.css' | url }}">
{% if palette.scheme or palette.primary or palette.accent %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.cef4c379.min.css' | url }}">
{% endif %}

View File

@ -168,6 +168,7 @@ nav:
- Buttons: reference/buttons.md
- Code blocks: reference/code-blocks.md
- Content tabs: reference/content-tabs.md
- Data tables: reference/data-tables.md
- Footnotes: reference/footnotes.md
- Formatting: reference/formatting.md
- Icons + Emojis: reference/icons-emojis.md

View File

@ -51,6 +51,14 @@ kbd {
// Rules: typesetted content
// ----------------------------------------------------------------------------
// Icon definitions
:root {
--md-typeset-table--ascending: svg-load("@mdi/svg/svg/arrow-down.svg");
--md-typeset-table--descending: svg-load("@mdi/svg/svg/arrow-up.svg");
}
// ----------------------------------------------------------------------------
// Content that is typeset - if possible, all margins, paddings and font sizes
// should be set in ems, so nested blocks (e.g. admonitions) render correctly,
// except headlines that should only appear on the top level and need to have
@ -437,7 +445,7 @@ kbd {
display: inline-block;
max-width: 100%;
overflow: auto;
font-size: px2em(12.8px);
font-size: px2rem(12.8px);
background: var(--md-default-bg-color);
border-radius: px2rem(2px);
box-shadow:
@ -521,6 +529,34 @@ kbd {
}
}
// Sortable tables
table th[role="columnheader"] {
cursor: pointer;
// Icons
&::after {
display: inline-block;
width: 1.2em;
height: 1.2em;
margin-left: 0.5em;
vertical-align: sub;
mask-repeat: no-repeat;
content: " ";
}
// Sort ascending
&[aria-sort="ascending"]::after {
background-color: currentColor;
mask-image: var(--md-typeset-table--ascending);
}
// Sort descending
&[aria-sort="descending"]::after {
background-color: currentColor;
mask-image: var(--md-typeset-table--descending);
}
}
// Wrapper for scrolling on overflow
&__scrollwrap {
margin: 1em px2rem(-16px);