Configuration Reference

Plugin Options

nav

An array of navigation items displayed in the header bar.

interface NavItem {
  label: string | Record<string, string>;
  href: string | Record<string, string>;
}

multiSidebar

Turns every top-level entry of the Starlight sidebar config into its own sidebar, with a switcher to move between them. Unset by default, which leaves Starlight’s single sidebar in place.

interface MultiSidebarOptions {
  switcherStyle?: "horizontalList" | "dropdown" | "hidden";
}

switcherStyle	Behavior
"horizontalList"	One tab per sidebar above the entries (default)
"dropdown"	A compact select listing every sidebar
"hidden"	No switcher, only the sidebar with the current page

Every top-level sidebar entry must be a group or autogenerated when this is set. See the multi-sidebar guide.

stylingSystem

Controls the CSS delivery mode.

Value	Behavior
"detect"	Auto-detect Tailwind (default)
"css"	Use pre-compiled CSS
"tailwind"	Use Tailwind processing

CSS Custom Properties

Layout

Property	Default	Description
--sl-content-width	55rem	Main content column width
--sl-sidebar-width	17rem	Left and right sidebar width
--sl-font	'Inter', system-ui, sans-serif	Primary font family

Colors

Override these in your custom CSS for a different palette.

Gray Scale

The theme maps Tailwind’s gray palette to Starlight’s 7-step gray scale (--sl-color-gray-1 through --sl-color-gray-7).

Semantic Colors

Property	Purpose
--sl-color-orange-*	Warning callouts
--sl-color-green-*	Success callouts
--sl-color-blue-*	Info callouts
--sl-color-purple-*	Custom callouts
--sl-color-red-*	Danger callouts

Component Overrides

The theme overrides 15 Starlight component slots, plus Sidebar when multiSidebar is set:

Component	Purpose
Header	Custom nav bar with configurable items
Search	Pagefind integration
ThemeProvider	FOUC prevention and theme initialization
ThemeSelect	3-way cycle toggle (Auto/Light/Dark)
PageFrame	Borderless sidebar layout
TwoColumnContent	Borderless right sidebar
Hero	Two-column responsive hero
Pagination	Custom prev/next links
SiteTitle	Custom logo/name layout
SocialIcons	Styled social links
MarkdownContent	Content wrapper
MobileMenuToggle	Hamburger button
MobileMenuFooter	Mobile nav drawer footer
MobileTableOfContents	Mobile TOC
LanguageSelect	i18n language picker
Sidebar	Multi-sidebar switcher, when enabled