Content tabs

Note

This document discusses content tabs, not navigation 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.

Linked Tabs

The linked content tabs feature seen in mkdocs-material is not supported until that feature transitions from the mkdocs-material theme’s insider releases to its public releases.

You can use other sphinx extensions (like sphinx-design tabs) to achieve this functionality. However, other extensions will require some custom CSS styling to match the mkdocs-material theme’s styling for 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

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 stuff

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;
}

Typical examples are seen in this documentations’ Custom admonitions and Version Information Structure sections.

Last update: Jul 26, 2022