Add AI documentation skills
This commit is contained in:
@@ -0,0 +1,191 @@
|
||||
---
|
||||
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/
|
||||
Reference in New Issue
Block a user