Configuration Options

This is the authoritative list of what the nebari() plugin accepts and what it sets on your behalf. For task-oriented guidance, see Configuration and Customizing the Theme.

Plugin options

Options passed to nebari(options):

Option	Type	Default	Description
`logoHref`	`string`	site base (`BASE_URL`)	URL the header logo links to. Set to a portal root for multi-pack domains.
`nav`	`{ label: string; href: string }[]`	unset	Top-level header tabs. Absent, the header is byte-identical to Starlight. Absolute hrefs link off-site and open in a new tab.

interface NebariThemeOptions {
  /** URL the header logo links to. Defaults to the site's own base. */
  logoHref?: string;
  /**
   * Top-level header tabs. When omitted, the header is byte-identical to
   * stock Starlight. Root-absolute hrefs get the site base prefixed;
   * absolute and protocol-relative ones are rendered verbatim and open in a
   * new tab.
   */
  nav?: Array<{ label: string; href: string }>;
}

What the plugin configures

When you register nebari(), it updates your Starlight config as follows. All of these are merged before your own config, so your values take precedence.

Setting	What the theme adds	Overridable
`customCss`	Font faces, Nebari tokens, theme mapping, and component styles — prepended before your own `customCss`.	Yes
`components`	Overrides the eight components listed below.	Yes
`social`	Prepends a GitHub link to `github.com/nebari-dev`.	Yes
`lastUpdated`	Defaults to `true`, so a date appears on pages that had none.	Yes

Overridden components

Component	Status	Why the theme overrides it
`SiteTitle`	Overridden	Renders the Nebari logo in the header.
`Head`	Overridden	Injects self-hosted font preloads.
`Footer`	Overridden	Adds the branded Nebari footer on splash pages.
`Sidebar`	Overridden	Injects the `nav` tabs into the mobile drawer.
`ThemeSelect`	Overridden	Swaps the `<select>` for the icon toggle.
`PageTitle`	Overridden	Renders breadcrumbs and the updated / read-time meta row.
`LastUpdated`	Overridden	Suppresses the duplicate date Starlight prints in the footer.
`MarkdownContent`	Overridden	Wraps tables so wide grids and long cells scroll instead of wrap, and tracks the last TOC heading at the bottom of the page.

Layout classes

These class names are a documented CSS contract. Use them in Markdown so a pack gets the landing and guides layouts without a versioned component API.

Class	Where	What it does
`.nbr-grid-3`	wrapping a `<CardGrid>`	Three-up cards that ladder to two, then one.
`.nbr-cols-2`	wrapping a Markdown list	Two-column popular-pages list, column-major, with trailing arrows.
`.nbr-chip`	a `<label>` next to a radio	Filter chip. The checked radio paints the filled accent pill.
`.nbr-guide-list`	wrapping `<GuideCard>`s	Stacked guide cards; also hides breadcrumbs, meta, and the title hairline.
`.nbr-404`	wrapping the 404 footnote	Splash 404 layout: centres the page, hides the footer, paints the wash.
`.nbr-table-scroll`	injected around tables	Horizontal scroll for a table that does not fit the column.

Import GuideCard from @nebari/starlight/components/GuideCard.astro.

Design tokens

The theme maps Nebari’s OKLCH tokens onto Starlight’s semantic variables. Override the Starlight-side variable, not the raw token, so your changes survive upgrades.

Variable	Role
`--sl-color-accent`	Links, active states, primary buttons
`--sl-color-accent-low`	Subtle accent backgrounds
`--sl-color-accent-high`	High-contrast accent text
`--sl-color-bg`	Page background
`--sl-color-text`	Body text

Compatibility

Dependency	Supported range	Notes
Starlight	`0.41.x`	Token mapping targets this major.
Astro	`7.x`	Peer of the supported Starlight range.
Node.js	`>= 18.17`	Bun `1.1+` also supported.