Starlight Search and Metadata Tutorial

What You Are Learning

This tutorial covers search and metadata for a Starlight documentation site. You will learn how page titles, descriptions, headings, frontmatter, and search-friendly writing help readers find what they need.

• How Starlight search fits into a documentation site.
• How to write useful titles and descriptions.
• How headings affect search and readability.
• How metadata improves previews and site structure.
• When external search such as Algolia DocSearch may be useful.

The Big Picture

Page content
  ↓
Frontmatter metadata
  ↓
Headings and links
  ↓
Search and navigation
  ↓
Reader finds the right page

Search is not only a technical feature. Search quality depends on how clearly the content is written and organized.

Basic Page Metadata

---
title: "Content Collections and Schemas"
description: "Learn how to organize Astro content with typed frontmatter schemas."
---

The title should identify the page. The description should explain why the page exists.

Weak vs Strong Titles

Search-Friendly Headings

Good:
## Deploying to Vercel
## Fixing Broken Image Paths
## Creating a Character Collection

Less useful:
## Step Three
## More Stuff
## Important Notes

Use descriptive section headings so both humans and search tools can understand the page.

Tags and Categories

---
title: "Mermaid Diagrams"
description: "Create flowcharts and diagrams in Astro Starlight."
category: "Special Features"
tags:
  - mermaid
  - diagrams
  - markdown
  - starlight
---

Use tags for topics. Use categories for broad sections.

Search Writing Tips

• Use the actual tool or topic name in the title.
• Repeat important terms naturally in headings and opening paragraphs.
• Include synonyms when useful, such as “deployment” and “publish online.”
• Avoid clever labels that hide the meaning of a page.
• Add glossary pages for repeated terms.

Built-In Search vs External Search

Built-in search is usually enough for small and medium tutorial sites, world bible sites, and internal documentation projects. External search can be useful when a public site grows to hundreds or thousands of pages.

Built-in search:
- Small and medium sites
- Personal docs
- Lesson libraries
- World bible references

External search:
- Large public docs
- Heavily used support sites
- Advanced ranking needs

Metadata Checklist

[ ] Every page has a clear title
[ ] Important pages have descriptions
[ ] Section headings use searchable terms
[ ] Tags are consistent
[ ] Categories are not too broad
[ ] Links use descriptive text
[ ] Glossary terms are defined
[ ] Index pages summarize each section

Simple Rule of Thumb

Good search starts with good writing.
Use clear titles.
Use descriptive headings.
Use consistent tags.
Use index pages.
Write for the reader first.