OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated content tabs and data table documentation

Browse Source
This commit is contained in:
squidfunk 2021-10-03 18:29:50 +02:00
parent df88640208
commit 69da0df6d5
5 changed files with 149 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/insiders/index.md
View File

@ -197,8 +197,8 @@ the public for general availability.
- [x] [Linking content tabs][32] - [x] [Linking content tabs][32]
[30]: ../setup/setting-up-site-search.md#search-boosting [30]: ../setup/setting-up-site-search.md#search-boosting
[31]: ../reference/admonitions.md#changing-the-icons [31]: ../reference/admonitions.md#admonition-icons
[32]: ../reference/content-tabs.md#linking-content-tabs [32]: ../reference/content-tabs.md#linked-content-tabs
#### $ 7,000 – Royal Gold #### $ 7,000 – Royal Gold

132
docs/reference/admonitions.md
View File

@ -32,6 +32,72 @@ See additional configuration options:
[Details]: ../setup/extensions/python-markdown-extensions.md#details [Details]: ../setup/extensions/python-markdown-extensions.md#details
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences [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 ## Usage
Admonitions follow a simple syntax: a block starts with `!!!`, followed by a 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 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. 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 ## Customization
### Custom admonitions ### Custom admonitions

1
docs/reference/code-blocks.md
View File

@ -40,6 +40,7 @@ See additional configuration options:
### Code annotations ### Code annotations
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } · [:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental · :octicons-beaker-24: Experimental ·
[:octicons-tag-24: insiders-2.2.0 ... present][Insiders] [:octicons-tag-24: insiders-2.2.0 ... present][Insiders]

130
docs/reference/content-tabs.md
View File

@ -11,53 +11,59 @@ grouping code blocks and other content.
## Configuration ## Configuration
### Tabbed This configuration enables content tabs, and allows to nest arbirtrary content
inside content tabs, including code blocks and ... more content tabs! Add the
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] following lines to `mkdocs.yml`
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:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- pymdownx.superfences - 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 ## Usage
@ -153,45 +159,11 @@ _Result_:
2. Donec vitae suscipit est 2. Donec vitae suscipit est
3. Nulla tempor lobortis orci 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 ### 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 content, including further content tabs, and can be nested in other blocks like
[admonitions][10], [details][11] or blockquotes: [admonitions] or blockquotes:
_Example_: _Example_:
@ -267,6 +239,4 @@ _Result_:
2. Donec vitae suscipit est 2. Donec vitae suscipit est
3. Nulla tempor lobortis orci 3. Nulla tempor lobortis orci
[9]: #superfences [admonitions]: admonitions.md
[10]: admonitions.md
[11]: admonitions.md#details

48
docs/reference/data-tables.md
View File

@ -6,15 +6,27 @@ template: overrides/main.html
Material for MkDocs defines default styles for data tables – an excellent way Material for MkDocs defines default styles for data tables – an excellent way
of rendering tabular data in project documentation. Furthermore, customizations of rendering tabular data in project documentation. Furthermore, customizations
like [sortable tables][1] can be achieved with a third-party library and some like [sortable tables] can be achieved with a third-party library and some
[additional JavaScript][2]. [additional JavaScript].
[1]: #sortable-tables [sortable tables]: #sortable-tables
[2]: ../customization.md#additional-javascript [additional JavaScript]: ../customization.md#additional-javascript
## Configuration ## 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 ## Usage
@ -22,7 +34,7 @@ None.
Data tables can be used at any position in your project documentation and can 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 contain arbitrary Markdown, including inline code blocks, as well as [icons and
emojis][3]. emojis].
_Example_: _Example_:
@ -42,12 +54,12 @@ _Result_:
| `PUT` | :material-check-all: Update resource | | `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource | | `DELETE` | :material-close: Delete resource |
[3]: icons-emojis.md [icons and emojis]: icons-emojis.md
### Column alignment ### Column alignment
If you want to align a specific column to the `left`, `center` or `right`, you 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. and/or end of the divider.
=== "Left" === "Left"
@ -110,17 +122,17 @@ and/or end of the divider.
| `PUT` | :material-check-all: Update resource | | `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete 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 ## Customization
### Sortable tables ### 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 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 ``` js
document$.subscribe(function() { document$.subscribe(function() {
@ -131,7 +143,7 @@ loading][6] via [additional JavaScript][2]:
}) })
``` ```
=== "`mkdocs.yml`" === ":octicons-file-code-16: mkdocs.yml"
``` yaml ``` yaml
extra_javascript: extra_javascript:
@ -139,9 +151,9 @@ loading][6] via [additional JavaScript][2]:
- javascripts/tables.js - javascripts/tables.js
``` ```
_Note that [tablesort][5] provides alternative comparison implementations like Note that [tablesort] provides alternative comparison implementations like
numbers, dates, filesizes and month names. See the official documentation for numbers, filesizes, dates and month names. See the [tablesort documentation]
more information._ [tablesort] for more information.
_Example_: _Example_:
@ -167,5 +179,5 @@ _Result_:
new Tablesort(tables.item(tables.length - 1)); new Tablesort(tables.item(tables.length - 1));
</script> </script>
[5]: http://tristen.ca/tablesort/demo/ [tablesort]: http://tristen.ca/tablesort/demo/
[6]: ../setup/setting-up-navigation.md#instant-loading [instant loading]: ../setup/setting-up-navigation.md#instant-loading