Organize steps, tabs, and code groups

Use steps when every action must happen in order. Use tabs when the reader chooses one alternative, and code groups when those alternatives are code examples. Keep required instructions visible; collapse only supplemental detail.

Sequence actions with stepsCopy Anchor Link

Place each action in a Step directly inside Steps. Give the action a title and include the result the reader should confirm before continuing. A step can contain prose, code, or a set of tabs when the action differs by environment.

This procedure creates a local file, then confirms its contents. Run both commands in the same directory.

printf 'ready\n' > component-check.txt

cat component-check.txt

Author the procedure with this MDX:

<Steps>
  <Step title="Create a test file">
    Write a single line to `component-check.txt`.

    ```sh title="Create file"
    printf 'ready\n' > component-check.txt
    ```

    The command finishes without output and creates the file.
  </Step>
  <Step title="Read the test file">
    Print the file to confirm that the write succeeded.

    ```sh title="Read file"
    cat component-check.txt
    ```

    Expected output is `ready` on one line.
  </Step>
</Steps>

The containers and step labels have these props:

Separate alternatives with tabsCopy Anchor Link

Use Tabs for mutually exclusive instructions such as operating systems or deployment targets. Put Tab elements directly inside Tabs, with a distinct title on each. Do not put a wrapper around the tab children: the parent reads their labels and assigns panel values.

This pair presents alternative instructions without making either one a prerequisite for the other:

Author those alternatives with this MDX:

<Tabs defaultValue="Local">
  <Tab title="Local">
    Run the file check in a working directory on your machine.
  </Tab>
  <Tab title="Container">
    Run the file check inside the container whose filesystem you want to test.
  </Tab>
</Tabs>

Use these authoring props to name panels and control selection:

Tabs with the same normalized label set synchronize their selection and retain the choice across navigation. A saved selection can override the initial default. Inactive content remains in the HTML but is hidden visually; tabs are not an access-control boundary.

Group code examplesCopy Anchor Link

Use CodeGroup for equivalent examples in different languages or tools. Put code fences directly inside the group and give every fence a title="…". The titles become selectable tab labels. Keep the inputs and expected results consistent across languages.

Both examples print ready followed by a newline:

console.log("ready");

Author the parallel examples with this MDX:

<CodeGroup>

```js title="JavaScript"
console.log("ready");
```

```python title="Python"
print("ready")
```

</CodeGroup>

The group itself accepts only its content:

Code groups with matching label sets synchronize their code selection. Avoid duplicate labels; repeated labels receive numeric suffixes to keep them selectable.

CodeGroup arranges examples but does not replace Markdown’s code syntax. For language identifiers and standalone blocks, see Format content.

Collapse optional detailCopy Anchor Link

Use an Accordion for a supplemental explanation with a visible label. Use AccordionGroup to coordinate several explanations, and Expandable for compact nested detail such as child attributes. Do not hide a required action or its expected result inside any of them.

A standalone accordion needs no surrounding group:

Author the standalone explanation with this MDX:

<Accordion title="Remove the test file" id="remove-test-file">
  Delete `component-check.txt` when the check is complete. Keep it if another example still needs it.
</Accordion>

Group related explanations to control how many can remain open:

Author that group with explicit values so its default does not depend on the display labels:

<AccordionGroup type="single" defaultValue="location">
  <Accordion title="Where is the file?" value="location">
    The file is in the directory where the write command ran.
  </Accordion>
  <Accordion title="What if it already exists?" value="overwrite">
    The write command replaces its previous contents.
  </Accordion>
</AccordionGroup>

For a shorter disclosure, Expandable supplies the show/hide wording:

Author that detail with this MDX:

<Expandable title="file details">
  The test file contains the word `ready` and a trailing newline.
</Expandable>

These props control labels, initial state, and linking:

A standalone accordion starts closed and can be closed after opening. Single-mode groups also permit closing the open item. In multiple mode, write an array expression such as defaultValue={["location", "overwrite"]}. Expandable uses a native details disclosure and does not participate in accordion group state.

Use viewsCopy Anchor Link

Use consecutive View blocks for alternative versions of a larger passage selected from a dropdown. Each run of adjacent sibling views becomes one selector group. Blank lines between views are fine; intervening prose or another component starts a separate group.

This pair renders a “Select view” control and displays one alternative at a time:

Author the views as separate blocks, without a group wrapper:

<View title="Workstation">
  Run the file check in your local working directory.
</View>

<View title="Build environment">
  Run the file check in the build's working directory.
</View>

The component has these authoring props:

Without site variation configuration, each group starts with its first view and keeps its selection local. With variations.options configured in docs.json, view titles match option labels case-insensitively. Matching groups share the selected option across the site, and the choice is saved in browser storage. The first configured option is the initial choice; a group without that option falls back to its first view. Matching menu choices appear in configuration order, followed by unmatched views in source order. Selecting an unmatched view changes only that group.

Views render all alternatives into the HTML and hide inactive passages. A link to a heading inside a hidden view activates that view. Server-rendered HTML uses the default selection; a saved browser choice applies after mount.

Do not author ViewGroup; the renderer creates the grouping. Inline View elements inside a paragraph are unsupported and render as their children with a warning. Views choose content variants, not human-versus-agent visibility.