Topbar

The 40px sticky bar at the top of the shell. Left to right: the brand cluster, the merged breadcrumb, the TabStrip, the search field, and the actions cluster (GitHub link, dev-mode dot, theme toggle).

Anatomy

┌─ 40px, sticky ──────────────────────────────────────────────────────┐
│ brand. subtitle [pkg|v0.2.0 ▾] [a1b2c3]  ┊crumb┊  TABS  [⌘K ⌕]  ○ ◐ │
│ └───────── brand cluster ─────────────┘           tabs   search  actions
└─────────────────────────────────────────────────────────────────────┘
   crumb = merged breadcrumb, fades in when the H1 scrolls under the bar

Props

The Layout owns the search state and passes it down; you only touch these props in a custom shell:

Everything else — brand, chips, tabs, links — comes from siteConfig and the TABS registry.

Brand cluster

{brand}. / {subtitle} renders from siteConfig, followed by any version chips and the git hash chip:

initDocs({
  site: {
    brand: 'DreamLake',
    subtitle: 'Dockit',
    versionChips: [{ label: 'dockit', version: __DOCKIT_VERSION__,
                     dropdown: true, manifestUrl: '/dockit-versions.json' }],
    gitHash: __GIT_HASH__,
  },
  // …
})

The chip values are the consumer's business — this site injects them via Vite define from the workspace package.json and git rev-parse --short=6 HEAD (see Releases & versioning for the full pattern).

• A chip with dropdown: true becomes the version switcher: it fetches its manifestUrl (default /versions.json) and lists aliases + past deploys in a keyboard-dismissable popover. These and every other badge in the shell share one visual idiom — see Chip for the spec and all the ways to inject badges.
• On version-subdomain deploys (v0-1-0.…), the chip re-labels itself from window.location.hostname after hydration. A custom product manifest must contain that version before the hostname can override the label; this prevents a docs-build version from relabeling a product badge.
• Chips can be scoped per tab: a TabDef.versionChips array overrides site.versionChips while that tab is active (omit to inherit, [] to show none). Handy for showing a cli-only chip on the CLI tab and none on a design tab — see Site config.
• prefix defaults to v; use prefix: '' for revision labels. This site's Python tab shows main plus its source revision without a dropdown, while Dockit's badge uses /dockit-versions.json.
• gitHash unset (empty) hides the hash chip entirely.

Breadcrumb merge

Scroll this page: once the H1 passes under the bar, the brand cluster collapses and a Doc Kit / Shell / Topbar breadcrumb fades in — the merge state from the Layout, read via useMerge(). breadcrumbRoot in siteConfig supplies the leftmost crumb; empty string omits it.

TabStrip

The compact tab cluster on the topbar's right side: uppercase mono labels with a sliding ink underbar that tracks the active (or hovered) tab. You can see it live at the top of this page — the Reference tab is active right now. <TabStrip> renders inline inside the topbar; it carries no sticky/blur/background of its own, and takes no props — all input comes from the TABS registry and the current URL via Vike's page context.

Data source

The strip renders the TABS registry, populated by initDocs({ tabs }) (or initTabs() directly). Each tab is a TabDef:

export interface TabDef {
  id: string        // stable key, e.g. 'components'
  label: string     // strip label, e.g. 'Components'
  numeral: string   // editorial chapter numeral, e.g. 'II'
  landing: string   // where clicking the tab navigates
  urlPrefix: string // pages under this prefix belong to the tab
}

This site's registry, for reference:

tabs: [
  { id: 'dockit', label: 'Dockit', numeral: 'I',
    landing: '/', urlPrefix: '/get-started' },
  { id: 'reference', label: 'Reference', numeral: 'II',
    landing: '/reference/config', urlPrefix: '/reference' },
  { id: 'python-autodoc', label: 'Python Autodoc', numeral: 'III',
    landing: '/python-autodoc', urlPrefix: '/python-autodoc' },
]

Behavior

• The active tab derives from the URL's first path segment (tabForUrl). / and unknown prefixes resolve to the first tab, so orphan pages never empty the sidebar.
• The Sidebar filters its groups to the active tab's pages — tabs are a lens, not separate sites. One tab can carry several sidebar sections: on this site the Reference tab (urlPrefix: '/reference') holds API, Shell, and Content components groups.
• The underbar tracks the hovered tab while the pointer is over the strip (measured with useLayoutEffect against live DOM rects, so it survives window resizes), then springs back to the active tab.
• Empty registry: with no tabs (tabs: [] or omitted), the strip renders nothing and the sidebar shows every section.

Search field

The field is a FLIP-animated fixed element: closed, it sits at the grid's right; open (⌘K — Ctrl+K on non-Mac — or /), it expands into the palette input. The animation measures the closed rect after each paint, so window resizes stay smooth. Below lg it collapses to an icon button.

Actions cluster

• GitHub link — siteConfig.repoUrl drives the icon; empty string hides it.
• DEV badge — a warn-variant Chip reading DEV appears while hidden pages are revealed (Cmd+Shift+D); clicking it turns the toggle back off. See Sidebar for what the toggle reveals.
• Theme toggle — light/dark/system; see Theming.

Related siteConfig fields