Content tabs¶

Use of content tabs in the mkdocs-material theme relies on a markdown extension that isn’t used in the world of Sphinx. Instead, the sphinx-immaterial theme provides its own directives to make use of content tabs.

.. md-tab-set::¶

Each set of tabs on a page must begin with a md-tab-set directive. This directive only accepts children that are md-tab-item directives.

:class: (string)¶

A space delimited list of qualified names that get used as the HTMl element’s class attribute.

:name: (string)¶

A qualified name that get used as the HTML element’s id attribute.

Use the ref role to reference the element by name.

This directive supports :class: and :name: options to use custom CSS classes and reference links (respectively).

md-tab-set Example¶

.. md-tab-set::
    :class: custom-tab-set-style
    :name: ref_this_tab_set

    .. md-tab-item:: Local Ref

        A reference to this tab set renders like so:
        `tab set description <ref_this_tab_set>`.

        This syntax can only be used on the same page as the tab set.

    .. md-tab-item:: Cross-page Ref

        To cross-reference this tab set from a different page, use
        :ref:`tab set description <ref_this_tab_set>`

        Clearly, this also works on the same page.

    .. md-tab-item:: Custom CSS

        .. literalinclude:: _static/extra_css.css
            :language: css
            :start-after: /* ************************ custom-tab-set-style
            :end-before: /* *********************** custom-tab-item-style

Local Ref Cross-page Ref Custom CSS

A reference to this tab set renders like so: tab set description.

This syntax can only be used on the same page as the tab set.

To cross-reference this tab set from a different page, use tab set description

Clearly, this also works on the same page.

.custom-tab-set-style {
  border: solid 2px var(--md-default-fg-color);
  padding: 0 5px;
}

.. md-tab-item::¶

This directive is used to create a tab within a set of content tabs. It requires a label as it’s argument.

:class: (string)¶

A space delimited list of qualified names that get used as the HTMl element’s class attribute.

Use the :class: option to optionally provide custom CSS classes to the tab’s content (not the tab’s label).

md-tab-item Example¶

.. md-tab-set::

    .. md-tab-item:: Customized content
        :class: custom-tab-item-style

        This content could be styled differently from other page content.

    .. md-tab-item:: Custom CSS

        .. literalinclude:: _static/extra_css.css
            :language: css
            :start-after: /* *********************** custom-tab-item-style
            :end-before: /* *********************** inline icon pulsing-heart style

Customized content Custom CSS

This content could be styled differently from other page content.

.custom-tab-item-style {
  border: solid 2px var(--md-default-fg-color);
  padding: 0 5px;
  margin-top: 3px;
}

Linked tabs¶

Content tabs that share the same label can be selected synchronously by adding "content.tabs.link" to the list of features in conf.py.

html_theme_options = {
    "features": [
        "content.tabs.link",
    ],

Synchronized selection will automatically persist across separate pages. Contradictory to the equivalent implementation in mkdocs-material theme, the "navigation.instant" feature does not need to be explicitly specified.

.. md-tab-set::

    .. md-tab-item:: Python

        .. code-block:: python

            def main():
                print("Hello world!")

    .. md-tab-item:: C++

        .. code-block:: cpp

            #include <iostream>

            int main(void) {
                std::cout << "Hello world!" << std::endl;
                return 0;
            }


.. md-tab-set::

    .. md-tab-item:: C only

        .. code-block:: c

            #include <stdio.h>

            int main(void) {
                printf("Hello world!\n");
                return 0;
            }

    .. md-tab-item:: C++

        .. code-block:: cpp

            #include <iostream>

            int main(void) {
                std::cout << "Hello world!" << std::endl;
                return 0;
            }

    .. md-tab-item:: Python

        .. code-block:: python

            def main():
                print("Hello world!")

def main():
    print("Hello world!")

#include <iostream>

int main(void) {
    std::cout << "Hello world!" << std::endl;
    return 0;
}

#include <stdio.h>

int main(void) {
    printf("Hello world!\n");
    return 0;
}

#include <iostream>

int main(void) {
    std::cout << "Hello world!" << std::endl;
    return 0;
}

def main():
    print("Hello world!")