1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-11 23:36:13 +01:00
mkdocs-material/docs/reference/content-tabs.md

244 lines
5.1 KiB
Markdown
Raw Normal View History

2020-07-20 19:28:13 +02:00
---
template: overrides/main.html
2021-12-16 17:08:57 +01:00
icon: material/tab
2020-07-20 19:28:13 +02:00
---
# Content tabs
Sometimes, it's desirable to group alternative content under different tabs,
e.g. when describing how to access an API from different languages or
environments. Material for MkDocs allows for beautiful and functional tabs,
grouping code blocks and other content.
2020-07-20 19:28:13 +02:00
## Configuration
2021-10-04 23:36:31 +02:00
This configuration enables content tabs, and allows to nest arbitrary content
inside content tabs, including code blocks and ... more content tabs! Add the
2021-10-04 23:36:31 +02:00
following lines to `mkdocs.yml`:
2020-07-20 19:28:13 +02:00
``` yaml
markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
```
2020-07-20 19:28:13 +02:00
See additional configuration options:
2020-07-20 19:28:13 +02:00
- [SuperFences]
- [Tabbed]
2021-10-02 15:24:09 +02:00
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
[Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed
2021-10-02 15:24:09 +02:00
### Linked content tabs
2021-10-02 15:24:09 +02:00
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
2021-10-10 17:39:53 +02:00
[:octicons-tag-24: insiders-2.9.0][Insiders] ·
:octicons-unlock-24: Feature flag ·
2021-10-10 17:39:53 +02:00
:octicons-beaker-24: Experimental
2021-10-02 15:24:09 +02:00
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`:
2021-10-02 15:24:09 +02:00
``` yaml
theme:
features:
- content.tabs.link
```
2021-10-02 15:24:09 +02:00
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.
2020-07-20 19:28:13 +02:00
2021-10-10 12:19:14 +02:00
=== ":octicons-check-circle-fill-16: Enabled"
2020-07-20 19:28:13 +02:00
2021-10-10 17:39:53 +02:00
[![content.tabs.link enabled]][content.tabs.link enabled]
2020-07-21 16:01:22 +02:00
2021-10-10 12:19:14 +02:00
=== ":octicons-skip-16: Disabled"
2020-07-21 16:01:22 +02:00
2021-10-10 17:39:53 +02:00
[![content.tabs.link disabled]][content.tabs.link disabled]
2020-07-21 16:01:22 +02:00
[Insiders]: ../insiders/index.md
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
2021-10-10 17:39:53 +02:00
[content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png
[content.tabs.link disabled]: ../assets/screenshots/content-tabs.png
2020-07-21 16:01:22 +02:00
2020-07-20 19:28:13 +02:00
## Usage
### Grouping code blocks
Code blocks are one of the primary targets to be grouped, and can be considered
a special case of content tabs, as tabs with a single code block are always
rendered without horizontal spacing.
_Example_:
```
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```
=== "C++"
``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
```
_Result_:
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```
=== "C++"
``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
### Grouping other content
When a content tab contains more than one code block, it is rendered with
horizontal spacing. Vertical spacing is never added, but can be achieved
by nesting tabs in other blocks.
_Example_:
```
=== "Unordered list"
2020-07-27 12:05:07 +02:00
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
2020-07-20 19:28:13 +02:00
=== "Ordered list"
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
_Result_:
=== "Unordered list"
2020-07-27 12:05:07 +02:00
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
2020-07-20 19:28:13 +02:00
=== "Ordered list"
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
### Embedded content
When [SuperFences] is enabled, content tabs can contain arbitrary nested
content, including further content tabs, and can be nested in other blocks like
[admonitions] or blockquotes:
2020-07-20 19:28:13 +02:00
2020-07-20 19:34:44 +02:00
_Example_:
``` markdown
2020-07-20 19:38:11 +02:00
!!! example
2020-07-20 19:34:44 +02:00
=== "Unordered List"
_Example_:
``` markdown
2020-07-27 12:05:07 +02:00
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
2020-07-20 19:34:44 +02:00
```
_Result_:
2020-07-27 12:05:07 +02:00
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
2020-07-20 19:34:44 +02:00
=== "Ordered List"
_Example_:
``` markdown
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
_Result_:
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
_Result_:
2020-07-20 19:38:11 +02:00
!!! example
2020-07-20 19:28:13 +02:00
2020-07-20 19:34:44 +02:00
=== "Unordered List"
2020-07-20 19:28:13 +02:00
_Example_:
``` markdown
2020-07-27 12:05:07 +02:00
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
2020-07-20 19:28:13 +02:00
```
_Result_:
2020-07-27 12:05:07 +02:00
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
2020-07-20 19:28:13 +02:00
2020-07-20 19:34:44 +02:00
=== "Ordered List"
2020-07-20 19:28:13 +02:00
_Example_:
``` markdown
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
_Result_:
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
[admonitions]: admonitions.md