Navigation, tabs, and sidebars

Basics

This page explains how to modify the navigation structure of your docs, which includes changing your header, tabs, and the content of your sidebars.

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

Change your header

Your site’s header lives at the very top of your site and contains your logo, the search box, several buttons, tabbed navigation, and more.

Header layouts

You have a choice of two layouts out of the box: default and stacked. The default layout condenses the header into a single row which 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 a few tabs, the default layout is generally preferable. Otherwise, opt for the stacked layout to give more room for your tabs to breathe.

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

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

Header buttons

You can add buttons to your header. Header buttons are commonly used to link to resources like your product’s dashboard or a getting started guide.

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

import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless-api/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 specify a specific variant property on each link object if you want to override this behavior.

Tabs and sidebars

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

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

Regardless of your choice between tabs or a global sidebar, changes to your API reference’s sidebar content should be made in your Stainless config.

The changes you make in your Stainless config will impact the output of the generateAPIReferenceItems() when it’s called in astro.config.ts as shown below.

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 each object defines one of 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 the default two-tab configuration:

import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless-api/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.

// ...
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",
  },
],
// ...

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.

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

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

See also: a more complete example.

import { defineConfig } from "astro/config";
import {
  generateAPIReferenceItems,
  stainlessDocs,
} from "@stainless-api/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
                },
              ],
            },
          ],
        }),
      ],
    });

Navigation, tabs, and sidebars

Change your header

Header layouts

Header buttons

Tabs and sidebars

Modify your API reference’s sidebar

Top-level tabs with sidebars

One global sidebar