Markdown versions of all docs pages are available by appending .md to any docs URL.

Groups tab shortcodes into one tabbed block, with page-unique DOM ids

Angle-bracket form only ({{< … >}}). The percent form would re-render the output as Markdown.

Parameters

Example

{{< tabs >}}
{{% tab name="Helm" %}}
Install with Helm.
{{% /tab %}}
{{% tab name="kubectl" %}}
Install with kubectl.
{{% /tab %}}
{{< /tabs >}}

Notes

Wraps a set of tab shortcodes into one tabbed block. Authoring is exactly Hextra’s — this shortcode shadows it to give each group DOM ids that are unique on the page, and to keep a group inside a gate from breaking the page around it.

Labelling and opening state

The labels come from each tab, not from this shortcode: name= sets the button text, and selected=true on one tab opens that tab instead of the first. The two parameters listed above are Hextra’s deprecated forms of the same two things, kept working for content that still uses them. items= on the group and tabName= on a tab are both dead ends — a tab with neither name= nor items= renders as “Tab 0”, “Tab 1”, with no build warning, so tests/tab-syntax.spec.ts lints for them in source.

Nesting

A whole tabs group may live inside a tab panel — the shape a “pick your platform, then pick your install method” procedure takes:

• An inner group switches independently of the group it sits in.
• An inner group is hidden and shown with its parent panel, and keeps its own selection when the parent is switched away and back.
• Nesting survives reuse and rebase, so a conref may carry the whole construction.

Two levels is the practical limit. Deeper renders, but it asks the reader to hold two choices in mind before any prose applies to them; prefer a second step, or a page per platform.

Syncing groups

Set tabs.sync in a page’s front matter, or page.tabs.sync in site params, and groups move together — pick Helm once and every Helm/kubectl group on the page follows.

The key is the tab NAMES, comma-joined, and nothing else. Not the position, not the nesting depth, not the containing panel. So two groups labelled the same are ONE control even when they are nested under different outer panels, and an inner group pairs with a top-level one across the nesting boundary. “Helm / kubectl” under both a Linux panel and a macOS panel is a single choice, not two. That is usually what a reader wants; when it is not, give the groups different labels. Pinned by tests/tabs-sync.spec.ts.

Inside a gate

A group may sit inside a version or conditional-text block, including inside a numbered step, and the step, the list, and the headings after the gate stay intact. There is no need to move the gated section into a snippet and gate a one-line reuse; that workaround still works, but it was only ever needed because of the bug this fixed. Pinned by tests/gate-tabs.spec.ts.

Flattening for PDF and Copy as Markdown

None of the JS runs in a PDF, the markdown output format, or the Copy-as-Markdown payload, so utils/unhide-tabs.html rewrites each group there: the button bar becomes “You can choose from the following options.” and every panel is unhidden under an Option: label carrying the name the reader would have clicked, nested groups included. Nothing is dropped — write tab content that still reads when every option is stacked in source order, and avoid “as shown in the tab above”.

Difference from Hextra’s tabs

Two things, neither of which changes how a group is written.

• DOM ids. Hextra derives them from the shortcode’s .Ordinal, which Hugo numbers relative to the parent shortcode, so every nested group collides with the page’s first group; this numbers them per page instead.
• Nested output is one line. A group inside another shortcode (a gate, steps, a tab, details) has its output flattened to a single line, the way reuse and callout already are. Hextra’s markup spans several lines, and inside a gate it is parsed as markdown again, where a line at column 0 ends the list item it sits in. A top-level group is unchanged.

The implementation comments in the source file have the full account.

Source: layouts/_shortcodes/tabs.html