Skip to content
Docs-as-Code Blueprint

Search & Sidebar Optimization

Astro Starlight manages sidebar navigation dynamically and powers internal search indexing via Pagefind. This guide explains how to optimize your content so users can find exactly what they need with zero backend latency.

How Search Works

Section titled “How Search Works”

Search is powered by Pagefind, a search library that runs entirely locally in the user’s browser. It indexes content during the static site build step, ensuring instant results without relying on external databases.

Search Optimization Checklist

Section titled “Search Optimization Checklist”

To ensure your articles rank properly in the internal search, follow these authoring best practices:

  • Descriptive Titles: Use action-oriented titles like How to Configure SSO instead of SSO Settings.
  • Keyword-Rich Descriptions: Pagefind gives extra weight to the frontmatter description field. Always include one.
  • Semantic Headings: Always use proper Markdown headers (##, ###). Pagefind anchors search results directly to individual section headings, allowing users to jump directly to the relevant step.
  • Synonyms in Introductory Text: Include common alternate phrasing in the opening paragraph (e.g., mentioning “API tokens” alongside “API keys”).

Customizing Sidebar Sorting

Section titled “Customizing Sidebar Sorting”

By default, Starlight sorts auto-generated sidebar articles alphabetically by file name. To customize the display order and label in the sidebar, use the sidebar object in your frontmatter:

---
title: Managing User Roles and Permissions
description: How to assign access levels to your team.
sidebar:
  order: 10
  label: User Roles
---