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.

​

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

{
  "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.

{
  "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".
• Do not reuse overlapping prefixes like "api" and "api-reference" unless you are sure about the ordering.
• 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.