Groups - Documentation.AI

Groups

Understand how Groups organize pages in the sidebar, when to use them, and how they differ from dropdowns and page-level grouping.

Overview

Groups are sidebar sections that organize related pages into clear, collapsible chunks like "Getting Started" or "API Documentation".

At the configuration level, a group is defined with properties such as group, icon, expandable, openapi, and pages. At the reader level, that same group appears as a labeled section in the left sidebar that can contain pages and nested sections.

Use groups when you want to:

For low-level configuration details, see Site Configuration. For UI-based workflows, read below.

Adding groups in the Web Editor

You can create groups directly from the Web Editor sidebar without touching configuration files. A Group is a labeled sidebar section that contains pages, created via Add Group from the Pages menu.

Select the correct Dimension and View:

  1. Open the Editor from your dashboard.
  2. In the sidebar, select the Dimension and View from the dropdowns at the top.
  3. The sidebar content list below updates for that Dimension + View.

When the sidebar shows Groups already exist:

When the sidebar section is still flat (only pages):

After you add a group, new pages at this level should be created inside groups.

Once groups exist at a level, new pages are created inside groups, not as root-level siblings. To keep navigation predictable, avoid mixing grouped and ungrouped content at the same level.

Add pages inside a group

When the sidebar shows Groups:

What a group is (and is not)

Groups in the navigation layer

In the navigation and site configuration, groups:

The pages array is where you structure the hierarchy of your sidebar.

How groups differ from dropdowns

"Dropdown" behavior in the header or navbar is separate from groups:

You can link a top-nav dropdown item into a group section, but the dropdown itself does not define groups or their structure.

How groups differ from page-level grouping

Some pages may use headings, tabs, or other components to group content inside a single page. That is page-level grouping, not navigation-level grouping.

A long conceptual guide might live as a single page inside one group, even if it uses headings, tabs, or other components to structure its internal content.

When to introduce groups vs keep flat pages

You do not need groups for every section. In many cases, a flat list of pages is simpler and easier to manage.

Use flat pages when

Flat sections are easier to maintain early on and avoid over-structuring.

Introduce groups when

Consider introducing groups inside a tab or section when:

From the Web Editor perspective, once you add a group at a level:

Avoid mixing grouped and ungrouped content at the same level. Decide whether a level should consist entirely of pages or entirely of groups, and keep that choice consistent.

What groups can contain

Groups define their children using a pages array. That array can hold:

These can be mixed in a single pages array.

Pages inside a group

A standard group may look like:

{
  "group": "Getting Started",
  "icon": "info",
  "expandable": true,
  "pages": [
    { "title": "Introduction", "path": "getting-started/introduction" },
    { "title": "Core concepts", "path": "getting-started/core-concepts" },
    { "title": "Quickstart", "path": "getting-started/quickstart" }
  ]
}

This renders a "Getting Started" section with three pages under it.

Nested groups

You can nest groups within other groups to add another level of structure:

{
  "group": "Customize",
  "icon": "palette",
  "expandable": true,
  "pages": [
    {
      "group": "SEO & GEO",
      "icon": "search-check-icon",
      "pages": [
        {
          "title": "Structured Data",
          "path": "seo-and-geo/structured-data"
        },
        {
          "title": "Sitemap",
          "path": "seo-and-geo/sitemap"
        }
      ]
    },
    {
      "title": "Site Configuration",
      "path": "customize/site-configuration"
    }
  ]
}

Here, "SEO & GEO" is a nested group inside "Customize", alongside other pages.

API/OpenAPI-backed groups

Groups can also bind directly to an OpenAPI specification using the openapi property in site configuration. In that case, the group acts as a container for generated API docs:

For practical organization patterns, see Organize API Reference and OpenAPI / JSON Schema Import.

How this fits with the "one-child" rule

In navigation, the key constraint is consistency at each level:

Internally, this keeps a clear parent-child relationship:

Content pages on groups

By default, a group is a structural container with no page of its own. When a reader clicks a group label in the sidebar, it expands or collapses the group; there is nothing to navigate to.

You can change this by attaching a content page to a group. A content page gives the group its own MDX-backed page with a unique path, so clicking the group label navigates to that page instead of only toggling expansion.

When to attach a content page

Attach a content page to a group when:

A content page on a group is optional. Most groups work fine without one. Add it only when readers would benefit from an overview or entry point for the section.

Add a content page in the Web Editor

Open the group settings

In the editor sidebar, find the group you want to edit. Click the menu icon (three dots) next to the group name and select Edit or Attach Content Page.

Configure the content page

Toggle Include Content Page on. Enter a path (slug) for the page, for example guides/overview. You can also browse unpublished pages to reuse an existing MDX file.

Write the content

The group now opens its content page when clicked. Write your overview, add Collection components, or use any other MDX content.

Add a content page in configuration

Add a path property to the group entry in your documentation.json:

{
  "group": "Getting Started",
  "icon": "info",
  "expandable": true,
  "path": "getting-started/overview",
  "pages": [
    { "title": "Introduction", "path": "getting-started/introduction" },
    { "title": "Quickstart", "path": "getting-started/quickstart" }
  ]
}

The path value follows the same rules as any page path: lowercase kebab-case, unique across your docs, and without the .mdx extension.

Display options on content pages

When a group has a content page, you can configure the same display options available on regular pages:

How content pages affect navigation

When a group has a content page:

Detach a content page

To remove a content page from a group without deleting the MDX file:

The MDX file remains as an unpublished page that you can reattach later or add elsewhere.

Practical patterns and gotchas

Common grouping patterns

Use these patterns as starting points for your sidebar:

Gotchas to avoid

Once you introduce a group at a level, convert other siblings at that level into groups too, instead of leaving some as raw pages.

Deeply nested groups make navigation harder. Prefer 2–3 levels of depth in the sidebar.

Use concise, action-neutral names that reflect content, such as "Customize", "Analytics", or "AI Features", rather than vague labels like "Misc" or "Other".

If a group will only ever contain one page, it may be simpler to keep that page at the parent level instead of wrapping it in a group.

When reorganizing an existing site, start by grouping the noisiest sections first (for example, API, integrations, or many small guides). Once those areas are structured, revisit smaller sections and only introduce groups where they improve scanability.

Where to configure and manage groups

You can manage groups in two primary ways:

Use whichever workflow fits your team: the Web Editor for everyday maintenance, and configuration files for bulk changes or version-controlled navigation.