Skip to content

Commit a479797

Browse files
paulbuzzbypaulbuzzby
committed
Examples
1 parent f887165 commit a479797

15 files changed

Lines changed: 2676 additions & 2 deletions

File tree

‎docs/Examples/admonitions.md‎

Lines changed: 539 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/Examples/code-blocks.md‎

Lines changed: 546 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/Examples/data-tables.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
icon: material/table-edit
3+
---
4+
5+
# Data tables
6+
7+
Material for MkDocs defines default styles for data tables – an excellent way
8+
of rendering tabular data in project documentation. Furthermore, customizations
9+
like [sortable tables] can be achieved with a third-party library and some
10+
[additional JavaScript].
11+
12+
[sortable tables]: #sortable-tables
13+
[additional JavaScript]: ../customization.md#additional-javascript
14+
15+
## Configuration
16+
17+
This configuration enables Markdown table support, which should normally be
18+
enabled by default, but to be sure, add the following lines to `mkdocs.yml`:
19+
20+
``` yaml
21+
markdown_extensions:
22+
- tables
23+
```
24+
25+
## Usage
26+
27+
Data tables can be used at any position in your project documentation and can
28+
contain arbitrary Markdown, including inline code blocks, as well as [icons and
29+
emojis]:
30+
31+
``` markdown title="Data table"
32+
| Method | Description |
33+
| ----------- | ------------------------------------ |
34+
| `GET` | :material-check: Fetch resource |
35+
| `PUT` | :material-check-all: Update resource |
36+
| `DELETE` | :material-close: Delete resource |
37+
```
38+
39+
<div class="result" markdown>
40+
41+
| Method | Description |
42+
| ----------- | ------------------------------------ |
43+
| `GET` | :material-check: Fetch resource |
44+
| `PUT` | :material-check-all: Update resource |
45+
| `DELETE` | :material-close: Delete resource |
46+
47+
</div>
48+
49+
[icons and emojis]: icons-emojis.md
50+
51+
### Column alignment
52+
53+
If you want to align a specific column to the `left`, `center` or `right`, you
54+
can use the [regular Markdown syntax] placing `:` characters at the beginning
55+
and/or end of the divider.
56+
57+
=== "Left"
58+
59+
``` markdown hl_lines="2" title="Data table, columns aligned to left"
60+
| Method | Description |
61+
| :---------- | :----------------------------------- |
62+
| `GET` | :material-check: Fetch resource |
63+
| `PUT` | :material-check-all: Update resource |
64+
| `DELETE` | :material-close: Delete resource |
65+
```
66+
67+
<div class="result" markdown>
68+
69+
| Method | Description |
70+
| :---------- | :----------------------------------- |
71+
| `GET` | :material-check: Fetch resource |
72+
| `PUT` | :material-check-all: Update resource |
73+
| `DELETE` | :material-close: Delete resource |
74+
75+
</div>
76+
77+
=== "Center"
78+
79+
``` markdown hl_lines="2" title="Data table, columns centered"
80+
| Method | Description |
81+
| :---------: | :----------------------------------: |
82+
| `GET` | :material-check: Fetch resource |
83+
| `PUT` | :material-check-all: Update resource |
84+
| `DELETE` | :material-close: Delete resource |
85+
```
86+
87+
<div class="result" markdown>
88+
89+
| Method | Description |
90+
| :---------: | :----------------------------------: |
91+
| `GET` | :material-check: Fetch resource |
92+
| `PUT` | :material-check-all: Update resource |
93+
| `DELETE` | :material-close: Delete resource |
94+
95+
</div>
96+
97+
=== "Right"
98+
99+
``` markdown hl_lines="2" title="Data table, columns aligned to right"
100+
| Method | Description |
101+
| ----------: | -----------------------------------: |
102+
| `GET` | :material-check: Fetch resource |
103+
| `PUT` | :material-check-all: Update resource |
104+
| `DELETE` | :material-close: Delete resource |
105+
```
106+
107+
<div class="result" markdown>
108+
109+
| Method | Description |
110+
| ----------: | -----------------------------------: |
111+
| `GET` | :material-check: Fetch resource |
112+
| `PUT` | :material-check-all: Update resource |
113+
| `DELETE` | :material-close: Delete resource |
114+
115+
</div>
116+
117+
[regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables
118+
119+
## Customization
120+
121+
### Sortable tables
122+
123+
If you want to make data tables sortable, you can add [tablesort], which is
124+
natively integrated with Material for MkDocs and will also work with [instant
125+
loading] via [additional JavaScript]:
126+
127+
=== ":octicons-file-code-16: `docs/javascripts/tablesort.js`"
128+
129+
``` js
130+
document$.subscribe(function() {
131+
var tables = document.querySelectorAll("article table:not([class])")
132+
tables.forEach(function(table) {
133+
new Tablesort(table)
134+
})
135+
})
136+
```
137+
138+
=== ":octicons-file-code-16: `mkdocs.yml`"
139+
140+
``` yaml
141+
extra_javascript:
142+
- https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
143+
- javascripts/tablesort.js
144+
```
145+
146+
After applying the customization, data tables can be sorted by clicking on a
147+
column:
148+
149+
``` markdown title="Data table, columns sortable"
150+
| Method | Description |
151+
| ----------- | ------------------------------------ |
152+
| `GET` | :material-check: Fetch resource |
153+
| `PUT` | :material-check-all: Update resource |
154+
| `DELETE` | :material-close: Delete resource |
155+
```
156+
157+
<div class="result" markdown>
158+
159+
| Method | Description |
160+
| ----------- | ------------------------------------ |
161+
| `GET` | :material-check: Fetch resource |
162+
| `PUT` | :material-check-all: Update resource |
163+
| `DELETE` | :material-close: Delete resource |
164+
165+
</div>
166+
167+
Note that [tablesort] provides alternative comparison implementations like
168+
numbers, filesizes, dates and month names. See the [tablesort documentation]
169+
[tablesort] for more information.
170+
171+
<script src="https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js"></script>
172+
<script>
173+
var tables = document.querySelectorAll("article table")
174+
new Tablesort(tables.item(tables.length - 1));
175+
</script>
176+
177+
[tablesort]: http://tristen.ca/tablesort/demo/
178+
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
179+
180+
### Import table from file
181+
182+
The plugin [mkdocs-table-reader-plugin][table-reader-docs] allows you to
183+
import data from a CSV or Excel file.
184+
185+
[table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/

0 commit comments

Comments
 (0)