Adding Search, Custom Domain, and Analytics

Overview

A documentation site needs search functionality, proper analytics, and optionally Google Analytics integration to track usage and improve content. This section covers how to add these essential features.

Q&A

Q: How does search work in Starlight?

A: Starlight integrates Pagefind, a fully static, local search engine. It requires zero configuration:

Pagefind indexes all content during the build process
A search UI is automatically added to the site header
Users can search across all pages with instant results

The search index is generated at build time and served as static files — no external API, no server needed.

To customize search behavior, you can add page-level metadata:

---
title: API Reference
pagefind:
  weight: 2          # Boost this page in search results
  filter:
    type: reference   # Enable filtering by content type
---

Q: Can I use Algolia DocSearch instead of Pagefind?

A: Yes, if you need more advanced features like analytics, typo tolerance, or synonym support:

Apply for Algolia DocSearch (free for open-source projects)
Install the Starlight Algolia plugin:

npm install starlight-algolia

Configure in astro.config.mjs:

import starlightAlgolia from 'starlight-algolia';

starlight({
  search: starlightAlgolia({
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'your_index_name',
  }),
})

For most documentation sites, the built-in Pagefind search is sufficient and simpler to maintain.

Q: How do I add Google Analytics?

A: Add the Google Analytics tracking script via Starlight’s head configuration:

const gaId = process.env.PUBLIC_GA_ID || 'G-XXXXXXXXXX';

export default defineConfig({
  integrations: [
    starlight({
      head: [
        {
          tag: 'script',
          attrs: { async: true, src: `https://www.googletagmanager.com/gtag/js?id=${gaId}` },
        },
        {
          tag: 'script',
          content: `window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', '${gaId}');`,
        },
      ],
    }),
  ],
});

Store the GA ID as an environment variable (PUBLIC_GA_ID) for security and environment-specific configuration.

Q: How do I add a custom favicon and logo?

A: Place favicon files in the public/ directory:

public/
├── favicon.svg      # SVG favicon (recommended)
├── favicon.ico      # Fallback for older browsers
└── logo.svg         # Logo for header

Starlight automatically picks up favicon.svg from the public directory. To customize the logo in the header:

starlight({
  logo: {
    src: './src/assets/logo.svg',
    alt: 'My Company Logo',
  },
})

Q: How do I improve SEO for my documentation site?

A: Starlight provides several SEO features out of the box:

Sitemap: Automatically generated at sitemap-index.xml
Meta tags: Title and description from frontmatter are used for SEO
Open Graph: Social media preview cards are auto-generated
Structured data: Breadcrumb schema for search engines

Additional SEO tips:

Write descriptive description in frontmatter for every page
Use semantic heading hierarchy (##, ###, ####)
Add alt text to all images
Submit your sitemap to Google Search Console
Set site in astro.config.mjs to your production URL

A: Configure social links and edit buttons in the Starlight config:

starlight({
  social: [
    { icon: 'github', label: 'GitHub', href: 'https://github.com/yourcompany/yourproject' },
    { icon: 'twitter', label: 'Twitter', href: 'https://twitter.com/yourcompany' },
    { icon: 'discord', label: 'Discord', href: 'https://discord.gg/yourinvite' },
  ],
  editLink: {
    baseUrl: 'https://github.com/yourcompany/yourproject/edit/main/',
  },
})

The edit link adds a “Edit this page” button on every page, encouraging community contributions.

Building a commercial IoT product?

We provide ESP32 ODM design-to-manufacturing services. From prototype to production — the team behind this tutorial can build it with you.

Talk to us →

Adding Search, Custom Domain, and Analytics