Site Search

By default, Starlight sites include full-text search powered by Pagefind, which is a fast and low-bandwidth search tool for static sites.

No configuration is required to enable search. Build and deploy your site, then use the search bar in the site header to find content.

Hide content in search results

Exclude a page

To exclude a page from your search index, add pagefind: false to the page’s frontmatter:

src/content/docs/not-indexed.md

---
title: Content to hide from search
pagefind: false
---

Exclude part of a page

Pagefind will ignore content inside an element with the data-pagefind-ignore attribute.

In the following example, the first paragraph will display in search results, but the contents of the <div> will not:

src/content/docs/partially-indexed.md

---
title: Partially indexed page
---

This text will be discoverable via search.

<div data-pagefind-ignore>

This text will be hidden from search.

</div>

Alternative search providers

Algolia DocSearch

If you have access to Algolia’s DocSearch program and want to use it instead of Pagefind, you can use the official Starlight DocSearch plugin.

1. Install @astrojs/starlight-docsearch:

   npm

   npm install @astrojs/starlight-docsearch

   pnpm

   pnpm add @astrojs/starlight-docsearch

   Yarn

   yarn add @astrojs/starlight-docsearch

2. Add DocSearch to your Starlight plugins config in astro.config.mjs and pass it your Algolia appId, apiKey, and indexName:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   import starlightDocSearch from '@astrojs/starlight-docsearch';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'Site with DocSearch',
         plugins: [
           starlightDocSearch({
             appId: 'YOUR_APP_ID',
             apiKey: 'YOUR_SEARCH_API_KEY',
             indexName: 'YOUR_INDEX_NAME',
           }),
         ],
       }),
     ],
   });

With this updated configuration, the search bar on your site will now open an Algolia modal instead of the default search modal.

DocSearch configuration

The Starlight DocSearch plugin supports customizing the DocSearch component with the following inline options:

• maxResultsPerGroup: Limit the number of results displayed for each search group. Default is 5.
• disableUserPersonalization: Prevent DocSearch from saving a user’s recent searches and favorites to local storage. Default is false.
• insights: Enable the Algolia Insights plugin and send search events to your DocSearch index. Default is false.
• searchParameters: An object customizing the Algolia Search Parameters.

Additional DocSearch options

A separate configuration file is required to pass function options like transformItems() or resultsFooterComponent() to the DocSearch component.

1. Create a TypeScript file exporting your DocSearch configuration.

   src/config/docsearch.ts

   import type { DocSearchClientOptions } from '@astrojs/starlight-docsearch';
   
   export default {
     appId: 'YOUR_APP_ID',
     apiKey: 'YOUR_SEARCH_API_KEY',
     indexName: 'YOUR_INDEX_NAME',
     getMissingResultsUrl({ query }) {
       return `https://github.com/algolia/docsearch/issues/new?title=${query}`;
     },
     // ...
   } satisfies DocSearchClientOptions;

2. Pass the path to your configuration file to the Starlight DocSearch plugin in astro.config.mjs.

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   import starlightDocSearch from '@astrojs/starlight-docsearch';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'Site with DocSearch',
         plugins: [
           starlightDocSearch({
             clientOptionsModule: './src/config/docsearch.ts',
           }),
         ],
       }),
     ],
   });

See the DocSearch JavaScript client API Reference for all supported options.

Translating the DocSearch UI

DocSearch only provides English UI strings by default. Add translations of the modal UI for your language using Starlight’s built-in internationalization system.

1. Extend Starlight’s i18n content collection definition with the DocSearch schema in src/content.config.ts:

   src/content.config.ts

   import { defineCollection } from 'astro:content';
   import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
   import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
   import { docSearchI18nSchema } from '@astrojs/starlight-docsearch/schema';
   
   export const collections = {
     docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
     i18n: defineCollection({
       loader: i18nLoader(),
       schema: i18nSchema({ extend: docSearchI18nSchema() }),
     }),
   };

2. Add translations to your JSON files in src/content/i18n/.

   These are the English defaults used by DocSearch:

   src/content/i18n/en.json

   {
     "docsearch.searchBox.clearButtonTitle": "Clear the query",
     "docsearch.searchBox.clearButtonAriaLabel": "Clear the query",
     "docsearch.searchBox.closeButtonText": "Close",
     "docsearch.searchBox.closeButtonAriaLabel": "Close",
     "docsearch.searchBox.placeholderText": "Search docs",
     "docsearch.searchBox.placeholderTextAskAi": "Ask AI: ",
     "docsearch.searchBox.placeholderTextAskAiStreaming": "Answering…",
     "docsearch.searchBox.searchInputLabel": "Search",
     "docsearch.searchBox.backToKeywordSearchButtonText": "Back to keyword search",
     "docsearch.searchBox.backToKeywordSearchButtonAriaLabel": "Back to keyword search",
   
     "docsearch.startScreen.recentSearchesTitle": "Recent",
     "docsearch.startScreen.noRecentSearchesText": "No recent searches",
     "docsearch.startScreen.saveRecentSearchButtonTitle": "Save this search",
     "docsearch.startScreen.removeRecentSearchButtonTitle": "Remove this search from history",
     "docsearch.startScreen.favoriteSearchesTitle": "Favorite",
     "docsearch.startScreen.removeFavoriteSearchButtonTitle": "Remove this search from favorites",
     "docsearch.startScreen.recentConversationsTitle": "Recent conversations",
     "docsearch.startScreen.removeRecentConversationButtonTitle": "Remove this conversation from history",
   
     "docsearch.errorScreen.titleText": "Unable to fetch results",
     "docsearch.errorScreen.helpText": "You might want to check your network connection.",
   
     "docsearch.footer.selectText": "to select",
     "docsearch.footer.submitQuestionText": "Submit question",
     "docsearch.footer.selectKeyAriaLabel": "Enter key",
     "docsearch.footer.navigateText": "to navigate",
     "docsearch.footer.navigateUpKeyAriaLabel": "Arrow up",
     "docsearch.footer.navigateDownKeyAriaLabel": "Arrow down",
     "docsearch.footer.closeText": "to close",
     "docsearch.footer.backToSearchText": "Back to search",
     "docsearch.footer.closeKeyAriaLabel": "Escape key",
     "docsearch.footer.poweredByText": "Search by",
   
     "docsearch.noResultsScreen.noResultsText": "No results for",
     "docsearch.noResultsScreen.suggestedQueryText": "Try searching for",
     "docsearch.noResultsScreen.reportMissingResultsText": "Believe this query should return results?",
     "docsearch.noResultsScreen.reportMissingResultsLinkText": "Let us know.",
   
     "docsearch.resultsScreen.askAiPlaceholder": "Ask AI: ",
   
     "docsearch.askAiScreen.disclaimerText": "Answers are generated by AI and may be inaccurate.",
     "docsearch.askAiScreen.relatedSourcesText": "Related sources",
     "docsearch.askAiScreen.thinkingText": "Thinking…",
     "docsearch.askAiScreen.copyButtonText": "Copy",
     "docsearch.askAiScreen.copyButtonCopiedText": "Copied!",
     "docsearch.askAiScreen.copyButtonTitle": "Copy",
     "docsearch.askAiScreen.likeButtonTitle": "Like",
     "docsearch.askAiScreen.dislikeButtonTitle": "Dislike",
     "docsearch.askAiScreen.thanksForFeedbackText": "Thanks for your feedback!",
     "docsearch.askAiScreen.preToolCallText": "Searching…",
     "docsearch.askAiScreen.duringToolCallText": "Searching ",
     "docsearch.askAiScreen.afterToolCallText": "Searched",
     "docsearch.askAiScreen.aggregatedToolCallText": "Searched"
   }

Algolia Ask AI

DocSearch v4 introduces an optional Ask AI conversational experience. To enable it, pass the askAi option to the Starlight DocSearch plugin — either as a plain string (your assistant ID) or as an object with overrides:

astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightDocSearch from '@astrojs/starlight-docsearch';

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightDocSearch({
          appId: 'YOUR_APP_ID',
          apiKey: 'YOUR_SEARCH_API_KEY',
          indexName: 'YOUR_INDEX_NAME',
          // simplest form — just the assistant ID
          // askAi: 'YOUR_ASSISTANT_ID',

          // or full form with per-assistant overrides
          askAi: {
            assistantId: 'YOUR_ASSISTANT_ID',
            // apiKey, appId & indexName default to the top-level values
            // but can be overridden individually if needed
            // apiKey: '...',
            // appId: '...',
            // indexName: '...',
          },
        }),
      ],
    }),
  ],
});

If you want to stick with keyword search only, simply omit the askAi property.