Skip to Content
rehype-code-group

Rich groups

Tabs that hold any Markdown, with a default tab, an accessible name, syncing, persistence and vertical orientation.

When a tab needs a sentence of context, a list of steps, or more than one code block, use a rich group. It has an outer :::: fence (four colons) and a ::: code-tab section (three colons) per tab.

:::: code-group label="Deploy target" default="pages"

::: code-tab label="Cloudflare Pages" value="pages"

Set the build command and output directory in the dashboard:

- Build command: `pnpm build`
- Output directory: `dist`

:::

::: code-tab label="Netlify" value="netlify"

Commit a `netlify.toml`:

```toml
[build]
command = "pnpm build"
publish = "dist"
```

:::

::::

Set the build command and output directory in the dashboard:

  • Build command: pnpm build
  • Output directory: dist

Commit a netlify.toml:

[build]
command = "pnpm build"
publish = "dist"

Group attributes

Attributes go on the opening :::: code-group line. All of them are optional.

AttributeValuesEffect
labelany textThe tab list's accessible name (aria-label). Defaults to Code examples.
defaulta tab's valueThe tab selected in the generated HTML. If no tab has that value, the first tab is selected.
syncany keyGroups with the same key switch together. See Sync and persistence.
persistlocal or urlRemembers the choice in local storage or the URL. Needs sync.
orientationhorizontal or verticalvertical stacks the tabs in a column and switches the arrow keys to up and down. Without it, tabs are horizontal.

Values that aren't listed, such as persist="session", are ignored, as are unknown attributes.

Tab attributes

AttributeRequiredEffect
labelyesThe text on the tab. It goes through the label resolver, so :package: npm shows as 📦 npm.
valuenoA stable identifier used by default, sync and persist. Defaults to the label exactly as written, before the resolver runs.

Give tabs a value whenever you use default, sync or persist. Then you can reword a label without breaking links, saved choices or other groups.

Writing attribute values

  • Quote values that contain spaces: label="Deploy target". Double quotes, single quotes and typographic quotes all work.
  • Values without spaces can go unquoted: default=pages. An unquoted value ends at the first space, so label=Deploy target gives the label Deploy.
  • Inside a quoted value, a backslash escapes a quote or another backslash.

Vertical tabs

orientation="vertical" suits groups with several tabs or long labels. On screens narrower than 40rem the bundled stylesheet puts the tabs back in a row above the panels; the keyboard still uses the up and down arrows.

:::: code-group label="Release checklist" orientation="vertical"

::: code-tab label="1. Version"

Run `pnpm changeset version` and review the generated changelog.

:::

::: code-tab label="2. Build"

```sh
pnpm build
```

:::

::: code-tab label="3. Publish"

Merge the release pull request. CI publishes to npm.

:::

::::

Run pnpm changeset version and review the generated changelog.

pnpm build

Merge the release pull request. CI publishes to npm.

Structure rules

  • Each marker line (:::: code-group, ::: code-tab …, ::: and ::::) must be a paragraph by itself, so surround it with blank lines.
  • Between tabs, only blank lines are allowed.
  • A tab can contain anything, including a compact group.
  • Rich groups can sit inside list items and block quotes.

Rich groups fail silently

If a rich group is malformed, for example a code-tab without a label, stray text between tabs, or a missing ::::, the plugin leaves the Markdown as it was. Unlike compact groups, it doesn't report a diagnostic. If you see :::: on the page, check those three things first.

Edit on GitHub