Tabs, sidebars & navigation

By default, Stainless Docs provides a tabbed navigation structure with two top-level tabs: Guides and Reference. The Guides tab contains your written content, and the Reference tab contains your auto-generated API reference.

Generally, documentation sites with extensive content (like guides plus an API reference) use top-level tabs because that structure provides easier and more intuitive navigation for large amounts of content.

If top-level tabs aren’t appropriate for your site, you can switch from top-level tabs to a global sidebar.

You can also add header buttons and adjust your header layout, regardless of your choice between top-level tabs or a single global sidebar.

Top-level tabs with sidebars

The tabs property in your astro.config.ts file defines the top-level tabs for your site. The tabs property contains an array of objects, where the objects define your tabs. Each tab object has two required properties: label and link. A third optional property, sidebar, allows you to define sidebar content for a specific tab.

Here’s an example of the Stainless Docs default two-tab configuration:

astro.config.ts

// ...
import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless/stl-starlight/stainless-docs";

export default defineConfig({
  integrations: [
    stainlessDocs({
      // ...
      tabs: [
        {
          label: "Guides",
          link: "/",
          sidebar: [
            {
              label: "Getting started",
              items: [""], // "" links to the index page
            },
            {
              label: "Guides",
              autogenerate: { directory: "guides" },
            },
          ],
        },
        {
          label: "API Reference",
          link: "/api",
          sidebar: [
            {
              label: "API Reference",
              items: generateAPIReferenceItems(),
            },
          ],
        },
      ],
    }),
  ],
});

See also: a more complex example.

astro.config.ts

// ...
tabs: [
  {
    label: "Guides",
    link: "/guides",
    sidebar: [
      "", // index page
      "quickstart",
      {
        label: "Installation",
        items: [
          "installation/macos",
          "installation/windows",
          "installation/linux",
        ],
      },
      {
        label: "Guides",
        autogenerate: { directory: "guides" },
      },
      {
        label: "Resources",
        items: [
          {
            label: "Community",
            link: "https://example.com/community", // external link
          },
          {
            label: "Support",
            link: "https://example.com/support",
          },
          {
            label: "FAQ",
            slug: "faq", // slug is the slug of a page in the docs content collection
          },
        ],
      },
    ],
  },
  {
    label: "Reference",
    link: "/api",
    sidebar: generateAPIReferenceItems(),
  },
  {
    label: "Support",
    link: "https://example.com/support",
  },
],
// ...

One global sidebar

If you want a simpler navigation structure for less extensive documentation, you can switch from top-level tabs with their own sidebars to a single global sidebar with no tabs.

To set up a global sidebar, remove the tabs property from your astro.config.ts file and add a sidebar property. The sidebar property will define the content of your global sidebar, and adheres to the same API as a Starlight sidebar.

Note

You can’t define both tabs and sidebar in your Stainless Docs astro.config.ts. If both are present, tabs will take precedence and sidebar will be ignored.

astro.config.ts

import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless/stl-starlight/stainless-docs";

export default defineConfig({
  integrations: [
    stainlessDocs({
      // ...
      sidebar: [
        "", // index page
        // ... add other pages here
      ],
    }),
  ],
});

See also: a more complete example.

astro.config.ts

import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless/stl-starlight/stainless-docs";

export default defineConfig({
integrations: [
  stainlessDocs({
    // ...
      sidebar: [
            "", // index page
            "quickstart",
            {
              label: "Installation",
              items: [
                "installation/macos",
                "installation/windows",
                "installation/linux",
              ],
            },
            {
              label: "API Reference",
              // returns an array of sidebar items for all API methods
              items: generateAPIReferenceItems(),
            },
            {
              label: "Guides",
              // generates items from pages in the 'guides' directory
              autogenerate: { directory: "guides" },
            },
            {
              label: "Resources",
              items: [
                {
                  label: "Community",
                  link: "https://example.com/community", // external link
                },
                {
                  label: "Support",
                  link: "https://example.com/support",
                },
                {
                  label: "FAQ",
                  slug: "faq", // slug is the slug of a page in the docs content collection
                },
              ],
            },
          ],
        }),
      ],
    });

Header buttons

In addition to links in your sidebars or tabs, you can add buttons to the header of your site. Commonly, these are used to link resources like your product’s dashboard or a getting started guide.

The following configuration will render two buttons in your site’s header:

astro.config.ts

import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless/stl-starlight/stainless-docs";

export default defineConfig({
  integrations: [
    stainlessDocs({
      // ...
      header: {
        links: [
          {
            label: "Feedback",
            link: "mailto:feedback@example.com",
          },
          {
            label: "Get started",
            link: "https://example.com/dashboard",
          },
        ],
      },
    }),
  ],
});

By default, the last item in the links array will be rendered using the default variant while all other items will be rendered using the outline variant. You can provide a variant property alongside label and link to override this behavior.

Header layouts

Stainless Docs provides two header layout options out of the box: default and stacked. The default layout condenses the header into a single row and takes up less vertical space, and the stacked layout moves your tabs to a second row under your site’s title.

If you only have one or two tabs, the default layout is generally preferable. Otherwise, opt for the stacked layout.

astro.config.ts

import { defineConfig } from "astro/config";
import { stainlessDocs } from "@stainless-api/docs";

export default defineConfig({
  integrations: [
    stainlessDocs({
      title: "My Docs",
      header: {
        layout: "stacked",
      },
    }),
  ],
});