Header

Your docs site keeps the same top bar on every page. You might want the logo alone without repeating the project name, a Sign up button beside search, or a cleaner bar when the GitHub star count is not part of your brand story.

The header is the sticky bar above page content. It holds identity on the left (logo, optional site name, branch preview badge) and actions on the right (optional Ask AI control, search, custom links, GitHub shortcut, theme toggle). When you configure navigation tabs, a second row under the main bar switches between major doc sections.

Most header behavior is controlled by the header object in docs.json. Logo images come from logo; the site title text comes from the top-level name field. Search, tabs, and the agent panel are separate features. They share the header layout but are not toggled through header.

Field names, types, and defaults live in docs.json.

The header stays fixed at the top of the viewport while readers scroll. A thin border fades in after the first scroll to separate the header from the page.

The main row is 56px tall and splits into two zones:

When tabs are configured, a compact tab strip appears below the main row. On small screens, a sidebar trigger sits beside the tabs so readers can open navigation without leaving the header.

The home link always points to /. If you set logo.light and/or logo.dark, the matching image renders at 24px height and switches with the active theme. See Logo for asset paths and light/dark pairing.

The site name from docs.json appears beside the logo when both of these are true:

• header.showName is true (the default)
• name is set and non-empty

Set showName to false when the logo already includes your wordmark or you want a minimal bar.

Several controls always occupy the right side of the header on hosted docs sites:

• Ask AI appears when the agent is enabled in docs.json. See Ask AI.
• Search opens the command palette for full-text search across your site. See Search.
• GitHub links to https://github.com/{owner}/{repo} for the hosted repository and shows a formatted star count on medium and larger viewports.
• Theme toggle switches between light and dark mode using your theme settings.

The header schema also defines showThemeToggle and showGitHubCard booleans (both default to true). Those fields are schema only. Theme toggle and GitHub link always render on hosted sites today. See docs.json: Schema-only fields.

Add outbound or in-site shortcuts with header.links, an array of link objects. Each entry needs title and href. Set cta to true to render a filled primary button; omit it or set false for an outline button.

{
  "header": {
    "showName": true,
    "links": [
      {
        "title": "Changelog",
        "href": "/changelog"
      },
      {
        "title": "Get started",
        "href": "https://app.example.com/signup",
        "cta": true
      }
    ]
  }
}

Links render after search and before the GitHub control, in array order. Use internal paths for docs pages and full URLs for external destinations.

The schema accepts an optional locale string on each link so a button could appear only for a given translation. That field is schema only. All configured links render on every locale today. See docs.json: Schema-only fields.

Header options compose with other customization without duplicating configuration:

• Logo supplies images; header decides whether the text name appears beside them.
• Tabs add the section switcher row; each tab still has its own sidebar tree.
• Theme sets colors and default mode; the header theme toggle lets readers override mode per session.
• Social links and Open Graph metadata affect sharing previews in the footer and meta tags, not the top bar itself. See Social links.

For a single workflow that walks through theme, logo, header, and footer together, see Branding.