Expandables - Documentation.AI

Expandables

Reference for creating collapsible content sections using the editor UI and the Expandable / ExpandableGroup components.

Overview

Expandables let you hide detailed content behind a clickable title. They are useful anywhere you want progressive disclosure in your docs instead of long, uninterrupted sections.

Use expandables to:

In Documentation.AI you can add expandables in two ways:

You can freely mix expandables with other components such as Callout and Steps to create richer, more scannable pages.

Using with Web Editor

In the Web Editor, Expandable and Expandable Group are available as blocks from the slash menu.

Add a single expandable

  1. Place your cursor on a new line where you want the collapsible section.
  2. Type / and search for Expandable.
  3. Select Expandable to insert an accordion-style block.
  4. Click the title text in the header to rename it.
  5. Click inside the content area to start adding body content.

Each expandable has:

Prefer writing in code?

You can switch to MDX view inside the Web Editor to write or edit this component using the same syntax as the Code Editor. This is useful if you want full control while staying in the Web Editor.

Control default open or closed

For each expandable block:

Add and manage an expandable group

Use Expandable Group when you want multiple expandables that belong together, such as an FAQ list or a set of configuration topics.

To add and manage a group:

  1. Place your cursor on a new line.
  2. Type / and search for Expandable Group, then insert it.
  3. Inside the group:
    • Use the + button at the bottom of the group to add another item.
    • Click the trash icon on an item to delete just that expandable.
    • Use the drag handle to reorder items.
    • Edit titles and content just like a single expandable.

Expandable Group ensures consistent spacing, borders, and behavior across all items in the group.

Using with Code Editor

In the Code Editor (MDX), you work directly with the <Expandable> and <ExpandableGroup> components.

<Expandable> component

Use <Expandable> for a single collapsible section.

<Expandable title="Click to expand" default-open="false">
  Add your content here...
</Expandable>

The two main attributes are:

<Expandable title="Getting started guide" default-open="true">
  This section starts open by default and is useful for key onboarding content.
</Expandable>

Expandables can contain rich content including lists, code blocks, Callout, and Steps:

<Expandable title="API configuration" default-open="false">
## Environment variables

Set these variables in your `.env` file:

- `API_KEY` - Your API authentication key
- `API_URL` - Base URL for API calls

```bash
# Example .env file
API_KEY=your-secret-key
API_URL=https://api.example.com
```

<Callout kind="danger">
  Never commit API keys to version control.
</Callout>
</Expandable>

<ExpandableGroup> component

Use <ExpandableGroup> to group multiple <Expandable> components together with consistent styling.

<ExpandableGroup>
  <Expandable title="Installation" default-open="true">
    Install the package using your preferred package manager:

```bash
    npm install documentation-ai
    ```
  </Expandable>

<Expandable title="Configuration" default-open="false">
    Create a configuration file in your project root:

```json
    {
      "name": "My Documentation",
      "theme": "light",
      "sidebar": true
    }
    ```
  </Expandable>

<Expandable title="Deployment" default-open="false">
    Deploy your documentation using the CLI:

```bash
    npm run deploy
    ```
  </Expandable>
</ExpandableGroup>

<ExpandableGroup> itself does not take any attributes; it is a simple wrapper that applies layout and spacing to the child <Expandable> components.

Attribute reference

[path

titlestring](/content/docs/components/expandables#path-title/index.html)

Header text displayed in the expandable button (default: "Click to expand").

[path

default-openstring](/content/docs/components/expandables#path-default-open/index.html)

Initial state: "true" (open) or "false" (closed). Defaults to "false".

Advanced options

Content and layout best practices

Keep pages scannable by showing only the essentials by default, and placing advanced details or edge cases in expandables.

Aim for clear, action-oriented titles such as "Advanced configuration", "Troubleshooting", or "See full example" rather than full sentences.

While you can place many components (including Callout and Steps) inside an expandable, avoid deeply nested expandables or many layers of headings, which can be harder to navigate.

Prefer <ExpandableGroup> when you have several related items so spacing, borders, and behavior feel consistent.

Behavioral notes and limitations