mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-30 18:24:35 +01:00
Updated content tabs and data table documentation
This commit is contained in:
squidfunk
parent
df88640208
commit
69da0df6d5
@ -197,8 +197,8 @@ the public for general availability.
|
||||
- [x] [Linking content tabs][32]
|
||||
|
||||
[30]: ../setup/setting-up-site-search.md#search-boosting
|
||||
[31]: ../reference/admonitions.md#changing-the-icons
|
||||
[32]: ../reference/content-tabs.md#linking-content-tabs
|
||||
[31]: ../reference/admonitions.md#admonition-icons
|
||||
[32]: ../reference/content-tabs.md#linked-content-tabs
|
||||
|
||||
#### $ 7,000 – Royal Gold
|
||||
|
||||
|
||||
@ -32,6 +32,72 @@ See additional configuration options:
|
||||
[Details]: ../setup/extensions/python-markdown-extensions.md#details
|
||||
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
|
||||
|
||||
### Admonition icons
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-2.4.0 ... present][Insiders]
|
||||
|
||||
Each of the supported admonition types has a distinct icon, which can be changed
|
||||
to any icon bundled with the theme. Just set the name of the admonition type to
|
||||
a valid icon in `mkdocs.yml`:
|
||||
|
||||
=== ":octicons-mark-github-16: Octicons"
|
||||
|
||||
_Example_:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
admonition:
|
||||
note: octicons/tag-16
|
||||
abstract: octicons/checklist-16
|
||||
info: octicons/info-16
|
||||
tip: octicons/squirrel-16
|
||||
success: octicons/check-16
|
||||
question: octicons/question-16
|
||||
warning: octicons/alert-16
|
||||
failure: octicons/x-circle-16
|
||||
danger: octicons/zap-16
|
||||
bug: octicons/bug-16
|
||||
example: octicons/beaker-16
|
||||
quote: octicons/quote-16
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[![Octicons]][Octicons]
|
||||
|
||||
|
||||
=== ":fontawesome-brands-font-awesome: FontAwesome"
|
||||
|
||||
_Example_:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
admonition:
|
||||
note: fontawesome/solid/sticky-note
|
||||
abstract: fontawesome/solid/book
|
||||
info: fontawesome/solid/info-circle
|
||||
tip: fontawesome/solid/bullhorn
|
||||
success: fontawesome/solid/check
|
||||
question: fontawesome/solid/question-circle
|
||||
warning: fontawesome/solid/exclamation-triangle
|
||||
failure: fontawesome/solid/bomb
|
||||
danger: fontawesome/solid/skull
|
||||
bug: fontawesome/solid/robot
|
||||
example: fontawesome/solid/flask
|
||||
quote: fontawesome/solid/quote-left
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[![FontAwesome]][FontAwesome]
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[Octicons]: ../assets/screenshots/admonition-octicons.png
|
||||
[FontAwesome]: ../assets/screenshots/admonition-fontawesome.png
|
||||
|
||||
## Usage
|
||||
|
||||
Admonitions follow a simple syntax: a block starts with `!!!`, followed by a
|
||||
@ -321,72 +387,6 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
as `Seealso`, which is incorrect English. For this reason, it was deprecated
|
||||
in :octicons-tag-24: 7.1.5 and will be removed in :octicons-tag-24: 8.0.0.
|
||||
|
||||
### Changing the icons
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-2.4.0 ... present][Insiders]
|
||||
|
||||
Each of the supported admonition types has a distinct icon, which can be changed
|
||||
to any icon bundled with the theme. Just set the name of the admonition type to
|
||||
a valid icon in `mkdocs.yml`:
|
||||
|
||||
=== ":octicons-mark-github-16: Octicons"
|
||||
|
||||
_Example_:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
admonition:
|
||||
note: octicons/tag-16
|
||||
abstract: octicons/checklist-16
|
||||
info: octicons/info-16
|
||||
tip: octicons/squirrel-16
|
||||
success: octicons/check-16
|
||||
question: octicons/question-16
|
||||
warning: octicons/alert-16
|
||||
failure: octicons/x-circle-16
|
||||
danger: octicons/zap-16
|
||||
bug: octicons/bug-16
|
||||
example: octicons/beaker-16
|
||||
quote: octicons/quote-16
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[![Admonition with Octicons icons][Octicons]][Octicons]
|
||||
|
||||
|
||||
=== ":fontawesome-brands-font-awesome: FontAwesome"
|
||||
|
||||
_Example_:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
admonition:
|
||||
note: fontawesome/solid/sticky-note
|
||||
abstract: fontawesome/solid/book
|
||||
info: fontawesome/solid/info-circle
|
||||
tip: fontawesome/solid/bullhorn
|
||||
success: fontawesome/solid/check
|
||||
question: fontawesome/solid/question-circle
|
||||
warning: fontawesome/solid/exclamation-triangle
|
||||
failure: fontawesome/solid/bomb
|
||||
danger: fontawesome/solid/skull
|
||||
bug: fontawesome/solid/robot
|
||||
example: fontawesome/solid/flask
|
||||
quote: fontawesome/solid/quote-left
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[![Admonition with FontAwesome icons][FontAwesome]][FontAwesome]
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[Octicons]: ../assets/screenshots/admonition-octicons.png
|
||||
[FontAwesome]: ../assets/screenshots/admonition-fontawesome.png
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom admonitions
|
||||
|
||||
@ -40,6 +40,7 @@ See additional configuration options:
|
||||
### Code annotations
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
:octicons-unlock-24: Feature flag ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: insiders-2.2.0 ... present][Insiders]
|
||||
|
||||
|
||||
@ -11,53 +11,59 @@ grouping code blocks and other content.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Tabbed
|
||||
|
||||
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
|
||||
|
||||
The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3],
|
||||
integrates with Material for MkDocs and can be enabled via `mkdocs.yml`:
|
||||
|
||||
=== "Modern"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true # (1)
|
||||
```
|
||||
|
||||
1. As of 7.3.1, support was added for the new [`alternate_style`][12] flag,
|
||||
which has much better behavior on smaller screen sizes, as content tabs
|
||||
are now scrollable and will overflow instead of break across multiple
|
||||
lines.
|
||||
|
||||
__The legacy style will be deprecated with the next major release.__
|
||||
|
||||
[12]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
|
||||
|
||||
=== "Legacy"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.tabbed
|
||||
```
|
||||
|
||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss
|
||||
[2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
|
||||
[3]: https://facelessuser.github.io/pymdown-extensions/
|
||||
|
||||
### SuperFences
|
||||
|
||||
The [SuperFences][4] extension, which is also part of [Python Markdown
|
||||
Extensions][3], allows for the __nesting of code and content blocks inside
|
||||
tabs__, and is therefore strongly recommended:
|
||||
This configuration enables content tabs, and allows to nest arbirtrary content
|
||||
inside content tabs, including code blocks and ... more content tabs! Add the
|
||||
following lines to `mkdocs.yml`
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
```
|
||||
|
||||
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||||
See additional configuration options:
|
||||
|
||||
- [SuperFences]
|
||||
- [Tabbed]
|
||||
|
||||
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
|
||||
[Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed
|
||||
|
||||
### Linked content tabs
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
:octicons-unlock-24: Feature flag ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: insiders-2.9.0 ... present][Insiders]
|
||||
|
||||
When enabled, all content tabs across the whole documentation site will be
|
||||
linked and switch to the same label when the user clicks on a tab. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- content.tabs.link
|
||||
```
|
||||
|
||||
Content tabs are linked based on their label, not offset. This means that all
|
||||
tabs with the same label will be activated when a user clicks a content tab
|
||||
regardless of order inside a container. Furthermore, this feature is fully
|
||||
integrated with [instant loading] and persisted across page loads.
|
||||
|
||||
=== "With linking"
|
||||
|
||||
[![With linking]][With linking]
|
||||
|
||||
=== "Without linking"
|
||||
|
||||
[![Without linking]][Without linking]
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
|
||||
[With linking]: ../assets/screenshots/content-tabs-link.png
|
||||
[Without linking]: ../assets/screenshots/content-tabs.png
|
||||
|
||||
## Usage
|
||||
|
||||
@ -153,45 +159,11 @@ _Result_:
|
||||
2. Donec vitae suscipit est
|
||||
3. Nulla tempor lobortis orci
|
||||
|
||||
### Linking content tabs
|
||||
|
||||
[:octicons-file-code-24: Source][5] ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders }
|
||||
|
||||
When _linking_ is enabled, all content tabs on a page will be linked and show
|
||||
the same active tab when the user clicks on a label. Add the following lines
|
||||
to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- content.tabs.link
|
||||
```
|
||||
|
||||
Content tabs are linked based on their label, not offset. This means that all
|
||||
tabs with the same label will be activated when a user clicks a content tab
|
||||
regardless of order inside a container. Furthermore, this feature is fully
|
||||
integrated with [instant loading][6] and persisted across page loads.
|
||||
|
||||
=== "With linking"
|
||||
|
||||
[![With linking][7]][7]
|
||||
|
||||
=== "Without linking"
|
||||
|
||||
[![Without linking][8]][8]
|
||||
|
||||
[5]: ../insiders/index.md
|
||||
[6]: ../setup/setting-up-navigation.md#instant-loading
|
||||
[7]: ../assets/screenshots/content-tabs-link.png
|
||||
[8]: ../assets/screenshots/content-tabs.png
|
||||
|
||||
### Embedded content
|
||||
|
||||
When [SuperFences][9] is enabled, content tabs can contain arbitrary nested
|
||||
When [SuperFences] is enabled, content tabs can contain arbitrary nested
|
||||
content, including further content tabs, and can be nested in other blocks like
|
||||
[admonitions][10], [details][11] or blockquotes:
|
||||
[admonitions] or blockquotes:
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -267,6 +239,4 @@ _Result_:
|
||||
2. Donec vitae suscipit est
|
||||
3. Nulla tempor lobortis orci
|
||||
|
||||
[9]: #superfences
|
||||
[10]: admonitions.md
|
||||
[11]: admonitions.md#details
|
||||
[admonitions]: admonitions.md
|
||||
|
||||
@ -6,15 +6,27 @@ template: overrides/main.html
|
||||
|
||||
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].
|
||||
like [sortable tables] can be achieved with a third-party library and some
|
||||
[additional JavaScript].
|
||||
|
||||
[1]: #sortable-tables
|
||||
[2]: ../customization.md#additional-javascript
|
||||
[sortable tables]: #sortable-tables
|
||||
[additional JavaScript]: ../customization.md#additional-javascript
|
||||
|
||||
## Configuration
|
||||
|
||||
None.
|
||||
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
|
||||
|
||||
@ -22,7 +34,7 @@ None.
|
||||
|
||||
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].
|
||||
emojis].
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -42,12 +54,12 @@ _Result_:
|
||||
| `PUT` | :material-check-all: Update resource |
|
||||
| `DELETE` | :material-close: Delete resource |
|
||||
|
||||
[3]: icons-emojis.md
|
||||
[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][4] placing `:` characters at the beginning
|
||||
can use the [regular Markdown syntax] placing `:` characters at the beginning
|
||||
and/or end of the divider.
|
||||
|
||||
=== "Left"
|
||||
@ -110,17 +122,17 @@ and/or end of the divider.
|
||||
| `PUT` | :material-check-all: Update resource |
|
||||
| `DELETE` | :material-close: Delete resource |
|
||||
|
||||
[4]: https://www.markdownguide.org/extended-syntax/#tables
|
||||
[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][5], which is
|
||||
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][6] via [additional JavaScript][2]:
|
||||
loading] via [additional JavaScript]:
|
||||
|
||||
=== "`docs/javascripts/tables.js`"
|
||||
=== ":octicons-file-code-16: docs/javascripts/tables.js"
|
||||
|
||||
``` js
|
||||
document$.subscribe(function() {
|
||||
@ -131,7 +143,7 @@ loading][6] via [additional JavaScript][2]:
|
||||
})
|
||||
```
|
||||
|
||||
=== "`mkdocs.yml`"
|
||||
=== ":octicons-file-code-16: mkdocs.yml"
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
@ -139,9 +151,9 @@ loading][6] via [additional JavaScript][2]:
|
||||
- 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._
|
||||
Note that [tablesort] provides alternative comparison implementations like
|
||||
numbers, filesizes, dates and month names. See the [tablesort documentation]
|
||||
[tablesort] for more information.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -167,5 +179,5 @@ _Result_:
|
||||
new Tablesort(tables.item(tables.length - 1));
|
||||
</script>
|
||||
|
||||
[5]: http://tristen.ca/tablesort/demo/
|
||||
[6]: ../setup/setting-up-navigation.md#instant-loading
|
||||
[tablesort]: http://tristen.ca/tablesort/demo/
|
||||
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
|
||||
|
||||
Loading…
Reference in New Issue
Block a user