2020-07-20 20:28:13 +03:00
|
|
|
---
|
|
|
|
template: overrides/main.html
|
2021-12-16 19:08:57 +03:00
|
|
|
icon: material/tab
|
2020-07-20 20:28:13 +03: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
|
2021-05-23 14:30:26 +03:00
|
|
|
environments. Material for MkDocs allows for beautiful and functional tabs,
|
|
|
|
grouping code blocks and other content.
|
2020-07-20 20:28:13 +03:00
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
2021-10-05 00:36:31 +03:00
|
|
|
This configuration enables content tabs, and allows to nest arbitrary content
|
2021-10-03 19:29:50 +03:00
|
|
|
inside content tabs, including code blocks and ... more content tabs! Add the
|
2021-10-05 00:36:31 +03:00
|
|
|
following lines to `mkdocs.yml`:
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
``` yaml
|
|
|
|
markdown_extensions:
|
|
|
|
- pymdownx.superfences
|
|
|
|
- pymdownx.tabbed:
|
|
|
|
alternate_style: true
|
|
|
|
```
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
See additional configuration options:
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
- [SuperFences]
|
|
|
|
- [Tabbed]
|
2021-10-02 16:24:09 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
|
|
|
|
[Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed
|
2021-10-02 16:24:09 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
### Linked content tabs
|
2021-10-02 16:24:09 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
2021-10-10 18:39:53 +03:00
|
|
|
[:octicons-tag-24: insiders-2.9.0][Insiders] ·
|
2021-10-03 19:29:50 +03:00
|
|
|
:octicons-unlock-24: Feature flag ·
|
2021-10-10 18:39:53 +03:00
|
|
|
:octicons-beaker-24: Experimental
|
2021-10-02 16:24:09 +03:00
|
|
|
|
2021-10-03 19:29:50 +03: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 16:24:09 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
``` yaml
|
|
|
|
theme:
|
|
|
|
features:
|
|
|
|
- content.tabs.link
|
|
|
|
```
|
2021-10-02 16:24:09 +03:00
|
|
|
|
2021-10-03 19:29:50 +03: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 20:28:13 +03:00
|
|
|
|
2021-10-10 13:19:14 +03:00
|
|
|
=== ":octicons-check-circle-fill-16: Enabled"
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2021-10-10 18:39:53 +03:00
|
|
|
[![content.tabs.link enabled]][content.tabs.link enabled]
|
2020-07-21 17:01:22 +03:00
|
|
|
|
2021-10-10 13:19:14 +03:00
|
|
|
=== ":octicons-skip-16: Disabled"
|
2020-07-21 17:01:22 +03:00
|
|
|
|
2021-10-10 18:39:53 +03:00
|
|
|
[![content.tabs.link disabled]][content.tabs.link disabled]
|
2020-07-21 17:01:22 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
[Insiders]: ../insiders/index.md
|
|
|
|
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
|
2021-10-10 18:39:53 +03:00
|
|
|
[content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png
|
|
|
|
[content.tabs.link disabled]: ../assets/screenshots/content-tabs.png
|
2020-07-21 17:01:22 +03:00
|
|
|
|
2020-07-20 20:28:13 +03: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
|
2022-01-10 16:31:58 +03:00
|
|
|
rendered without horizontal spacing:
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
``` title="Content tabs with code blocks"
|
2020-07-20 20:28:13 +03:00
|
|
|
=== "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;
|
|
|
|
}
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
<div class="result" markdown>
|
2020-07-20 20:28:13 +03:00
|
|
|
|
|
|
|
=== "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;
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
</div>
|
|
|
|
|
2020-07-20 20:28:13 +03:00
|
|
|
### 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
|
2022-01-10 16:31:58 +03:00
|
|
|
by nesting tabs in other blocks:
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
``` title="Content tabs"
|
2020-07-20 20:28:13 +03:00
|
|
|
=== "Unordered list"
|
|
|
|
|
2020-07-27 13:05:07 +03:00
|
|
|
* Sed sagittis eleifend rutrum
|
|
|
|
* Donec vitae suscipit est
|
|
|
|
* Nulla tempor lobortis orci
|
2020-07-20 20:28:13 +03:00
|
|
|
|
|
|
|
=== "Ordered list"
|
|
|
|
|
|
|
|
1. Sed sagittis eleifend rutrum
|
|
|
|
2. Donec vitae suscipit est
|
|
|
|
3. Nulla tempor lobortis orci
|
|
|
|
```
|
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
<div class="result" markdown>
|
2020-07-20 20:28:13 +03:00
|
|
|
|
|
|
|
=== "Unordered list"
|
|
|
|
|
2020-07-27 13:05:07 +03:00
|
|
|
* Sed sagittis eleifend rutrum
|
|
|
|
* Donec vitae suscipit est
|
|
|
|
* Nulla tempor lobortis orci
|
2020-07-20 20:28:13 +03:00
|
|
|
|
|
|
|
=== "Ordered list"
|
|
|
|
|
|
|
|
1. Sed sagittis eleifend rutrum
|
|
|
|
2. Donec vitae suscipit est
|
|
|
|
3. Nulla tempor lobortis orci
|
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
</div>
|
|
|
|
|
2020-07-20 20:28:13 +03:00
|
|
|
### Embedded content
|
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
When [SuperFences] is enabled, content tabs can contain arbitrary nested
|
2020-07-23 16:34:43 +03:00
|
|
|
content, including further content tabs, and can be nested in other blocks like
|
2021-10-03 19:29:50 +03:00
|
|
|
[admonitions] or blockquotes:
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
``` title="Content tabs in admonition"
|
2020-07-20 20:38:11 +03:00
|
|
|
!!! example
|
2020-07-20 20:34:44 +03:00
|
|
|
|
|
|
|
=== "Unordered List"
|
|
|
|
|
2022-04-24 14:56:55 +03:00
|
|
|
``` markdown
|
2020-07-27 13:05:07 +03:00
|
|
|
* Sed sagittis eleifend rutrum
|
|
|
|
* Donec vitae suscipit est
|
|
|
|
* Nulla tempor lobortis orci
|
2020-07-20 20:34:44 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
=== "Ordered List"
|
|
|
|
|
2022-04-24 14:56:55 +03:00
|
|
|
``` markdown
|
2020-07-20 20:34:44 +03:00
|
|
|
1. Sed sagittis eleifend rutrum
|
|
|
|
2. Donec vitae suscipit est
|
|
|
|
3. Nulla tempor lobortis orci
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
<div class="result" markdown>
|
2020-07-20 20:34:44 +03:00
|
|
|
|
2020-07-20 20:38:11 +03:00
|
|
|
!!! example
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2020-07-20 20:34:44 +03:00
|
|
|
=== "Unordered List"
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2022-04-24 14:56:55 +03:00
|
|
|
``` markdown
|
2020-07-27 13:05:07 +03:00
|
|
|
* Sed sagittis eleifend rutrum
|
|
|
|
* Donec vitae suscipit est
|
|
|
|
* Nulla tempor lobortis orci
|
2020-07-20 20:28:13 +03:00
|
|
|
```
|
|
|
|
|
2020-07-20 20:34:44 +03:00
|
|
|
=== "Ordered List"
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2022-04-24 14:56:55 +03:00
|
|
|
``` markdown
|
2020-07-20 20:28:13 +03:00
|
|
|
1. Sed sagittis eleifend rutrum
|
|
|
|
2. Donec vitae suscipit est
|
|
|
|
3. Nulla tempor lobortis orci
|
|
|
|
```
|
|
|
|
|
2022-01-10 16:31:58 +03:00
|
|
|
</div>
|
2020-07-20 20:28:13 +03:00
|
|
|
|
2021-10-03 19:29:50 +03:00
|
|
|
[admonitions]: admonitions.md
|