1. Settings
  2. Tabs

Tabs create top-level navigation in the header. Use them when a documentation site has major areas that deserve separate sidebars, such as Home, Guides, API Reference, SDKs, or CLI.

Tabs are different from the content-level <Tabs> MDX component. This page covers site navigation tabs in layout.json.

Guides tab selected with the Guides sidebar visible

The active Guides tab has its own sidebar. Home and API Reference remain accessible.

​
When to use tabs

Use tabs when users need to switch between large content areas.

  • Use Home or Guides for product documentation and onboarding.
  • Use API Reference for generated OpenAPI pages.
  • Use SDKs for language-specific implementation guides.
  • Use CLI for command-line workflows if they are large enough to deserve their own lane.

Do not use tabs for small groups of related pages. Use sidebar groups or dropdowns instead.

​
How tabs work

DocsAlot matches each tab to a route prefix.

For example, a tab with "url": "api-reference" shows sidebar groups whose pages live under /api-reference/*.

The default documentation tab is created from topAnchor. You do not need to add it to the tabs array.

​
Basic example

layout.json
{
  "topAnchor": {
    "name": "Home",
    "icon": "house",
    "iconType": "solid"
  },
  "tabs": [
    {
      "name": "API Reference",
      "url": "api-reference",
      "icon": "square-terminal",
      "iconType": "regular"
    }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["quickstart", "installation"]
    },
    {
      "group": "API Reference",
      "pages": ["api-reference/index", "api-reference/authentication"]
    },
    {
      "group": "Users",
      "pages": [
        "api-reference/users/list-users",
        "api-reference/users/create-user"
      ]
    }
  ]
}

With this setup:

  • Home shows quickstart and installation.
  • API Reference shows the groups whose pages start with api-reference.

​
Multiple tabs

Add one tab per major content area. Keep prefixes distinct so the active tab is obvious.

layout.json
{
  "topAnchor": {
    "name": "Home",
    "icon": "house"
  },
  "tabs": [
    {
      "name": "Guides",
      "url": "guides",
      "icon": "book-open",
      "iconType": "regular"
    },
    {
      "name": "API",
      "url": "api-reference",
      "icon": "cloud",
      "iconType": "regular"
    },
    {
      "name": "SDKs",
      "url": "sdks",
      "icon": "code",
      "iconType": "solid"
    }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["quickstart"]
    },
    {
      "group": "Guides",
      "pages": ["guides/install", "guides/configure"]
    },
    {
      "group": "API Reference",
      "pages": ["api-reference/index", "api-reference/authentication"]
    },
    {
      "group": "SDKs",
      "pages": ["sdks/javascript", "sdks/python"]
    }
  ]
}

​
Icon options

Each tab supports:

  • name: the label shown in the header
  • url: the route prefix or external URL
  • icon: a Font Awesome icon name, or none
  • iconType: regular, solid, duotone, brands, light, thin, or sharp-solid
  • hidden: hides the tab without removing it from the config

DocsAlot also accepts tab instead of name, and href instead of url, for Mintlify-style configs.

​
Agent-first setup

If you use the DocsAlot CLI with Claude, Codex, or another coding agent, ask for the outcome instead of editing every path manually.

use docsalot cli to add a top-level API Reference tab to this documentation, move all api-reference pages under it, update layout.json, and run a preview locally

After reviewing the preview, publish it:

use docsalot cli to push this documentation to remote and publish

​
Common mistakes

  • Do not include a leading slash in internal tab URLs. Use "api-reference", not "/api-reference".
  • Avoid nested prefixes like "guides" and "guides/sdk" for separate tabs; keep each section’s ownership clear.
  • Do not add the default Home tab to the tabs array. Configure it with topAnchor.
  • Make sure the pages for each tab actually use that tab’s route prefix.