Tabs and Code Groups

Tabs show alternatives in one place: instructions for each operating system, or the same setting in two formats. Readers see the one they pick, and the others stay out of their way.

#Tabs

::: tabs
== macOS
Install Node.js with [Homebrew](https://brew.sh):

```bash
brew install node
```
== Windows
Download the installer from [nodejs.org](https://nodejs.org) and run it.
== Linux
Use your distribution's package manager, for example `sudo apt install nodejs`.
:::

brew install node

• Each == Label line starts a tab. The label is plain text.
• A tab holds any Markdown: paragraphs, lists, code blocks, alerts and other components.
• The first tab shows first.
• Text before the first label is left out. A tabs container without any label is shown as text.

#Code groups

For the same code in several variants, a code group is shorter: each code block becomes a tab, named in square brackets after its language.

::: code-group
```bash [npm]
npm install --save-dev clay-doc
```
```bash [pnpm]
pnpm add -D clay-doc
```
```bash [yarn]
yarn add -D clay-doc
```
:::

npm install --save-dev clay-doc

pnpm add -D clay-doc

yarn add -D clay-doc

The tabs sit in a bar on top of the code. With shell code in a tab, the bar is a terminal’s: a window’s three buttons come before the tabs, and each command gets its $. windowDots: false in the theme leaves out the buttons.

• Without a name in brackets, a tab is named after the language, like yaml or json.
• Everything else of code blocks works, like highlighted lines: ```ts [clay.config.ts] {2}.
• Text between the code blocks of a group is left out.

#Other languages

Code in other languages has the same bar, without the buttons. Without names in brackets, the tabs are named after the languages:

::: code-group
```ts
const pages: string[] = await loadPages("docs");
console.log(`${pages.length} pages`);
```
```js
const pages = await loadPages("docs");
console.log(`${pages.length} pages`);
```
:::

const pages: string[] = await loadPages("docs");
console.log(`${pages.length} pages`);

const pages = await loadPages("docs");
console.log(`${pages.length} pages`);

#Shell code and other code

One tab of shell code is enough for the buttons, like bash next to PowerShell:

::: code-group
```bash [macOS and Linux]
export CLAY_BASE_URL="/preview/"
npx clay build
```
```powershell [Windows]
$env:CLAY_BASE_URL = "/preview/"
npx clay build
```
:::

export CLAY_BASE_URL="/preview/"
npx clay build

$env:CLAY_BASE_URL = "/preview/"
npx clay build

#Text and file names

A code group holds only code. For text next to the code, or a file name above it, use tabs with code blocks inside:

::: tabs
== GitHub Pages
Build in the workflow and upload `publish/public`:

```yaml [.github/workflows/deploy.yaml]
- run: npm ci
- run: npx clay build --strict
- uses: actions/upload-pages-artifact@v3
  with:
    path: publish/public
```
== Netlify
Netlify reads its settings from a file in the repository:

```toml [netlify.toml]
[build]
  command = "npx clay build --strict"
  publish = "publish/public"
```
:::

- run: npm ci
- run: npx clay build --strict
- uses: actions/upload-pages-artifact@v3
  with:
    path: publish/public

[build]
  command = "npx clay build --strict"
  publish = "publish/public"

#The reader’s choice is remembered

Picking a tab picks the tab of the same name in every group on the page, and Clay remembers it: a reader who chose pnpm once sees pnpm in every group on every page, also on their next visit. The choice is kept in the reader’s browser only.

#Keyboard

Tab moves to the tabs, ← and → switch between them, Home and End jump to the first and the last tab.

#Search

The search finds the text of every tab. Opening a result that is in a hidden tab shows that tab.