Build a Manual with Starlight #2: Sidebar and Search — Structuring Your Docs

Framework Starlight Documentation Static Site
3 min read

In #1 we brought up our first doc with Starlight. When you have only one or two pages, structure is not a problem. The problem arises when the docs grow to dozens of pages. A manual needs to let the reader always know “where the item they are looking at sits within the whole.” The things that play that role are the sidebar and search.

This series is Build a Manual with Starlight, in six parts.

  • #1 From Install to Your First Doc
  • #2 Sidebar and Search — Structuring Your Docs ← this post
  • #3 Writing Content — Code Blocks, Mermaid, asides
  • #4 Deploy to Cloudflare Pages and Connect a Domain
  • #5 Multilingual and Versioning
  • #6 Maintenance — Search, Accessibility, Docs Culture

In this post we cover configuring the sidebar automatically and manually and checking out the built-in search.

The Sidebar Is Defined in Config #

Starlight’s sidebar is defined inside the Starlight integration in astro.config.mjs. There are two approaches. The first builds it automatically by following the folders.

astro.config.mjs — autogenerate 
starlight({
  title: 'Product Manual',
  sidebar: [
    { label: 'Guides', autogenerate: { directory: 'guides' } },
  ],
})

The docs inside the guides folder are automatically sorted into the Guides group. The order of each page is adjusted with sidebar.order in the front matter.

Defining It Yourself #

If you want full control over the order and structure, write the items out yourself.

astro.config.mjs — define manually 
sidebar: [
  { label: 'Getting Started', link: '/intro/' },
  {
    label: 'Guides',
    items: [
      { label: 'Install', link: '/guides/install/' },
      { label: 'Configuration', link: '/guides/config/' },
    ],
  },
]

label is the name shown in the sidebar, and link is the doc path.

Search — Built In #

The good news is that you do not need to bolt search on separately. Starlight has Pagefind built in by default. It builds an index at build time, splits it into small pieces, and the browser fetches only the pieces it needs for a query, so it stays light even with many docs. No server or external service is required, and docs in languages including Korean search fine.

Search does not appear on the dev server; it works in the output built with npm run build. That is because the index is created by scanning the build output.

Wrapping Up #

In this post we configured the sidebar automatically and manually, and checked out the built-in Pagefind search. The fact that you do not have to worry about search separately makes structuring your information much lighter work.

In the next post we cover writing content. From code blocks and Mermaid diagrams to asides that highlight cautions and warnings, we will go over the elements that make docs pleasant to read.

X