---
title: Site Search
description: Learn about Starlight’s built-in site search features and how to customize them.
tableOfContents:
  maxHeadingLevel: 4
---

import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';

By default, Starlight sites include full-text search powered by [Pagefind](https://pagefind.app/), 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`](/reference/frontmatter/#pagefind) to the page’s frontmatter:

```md title="src/content/docs/not-indexed" ins={3}
---
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`](https://pagefind.app/docs/indexing/#removing-individual-elements-from-the-index) attribute.

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

```md title="src/content/docs/partially-indexed" ins="data-pagefind-ignore"
---
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](https://docsearch.algolia.com/) and want to use it instead of Pagefind, you can use the official Starlight DocSearch plugin.

<Steps>

1. Install `@astrojs/starlight-docsearch`:

   <Tabs syncKey="pkg">

   <TabItem label="npm">

   ```sh
   npm install @astrojs/starlight-docsearch
   ```

   </TabItem>

   <TabItem label="pnpm">

   ```sh
   pnpm add @astrojs/starlight-docsearch
   ```

   </TabItem>

   <TabItem label="Yarn">

   ```sh
   yarn add @astrojs/starlight-docsearch
   ```

   </TabItem>

   </Tabs>

2. Add DocSearch to your Starlight [`plugins`](/reference/configuration/#plugins) config in `astro.config.mjs` and pass it your Algolia `appId`, `apiKey`, and `indexName`:

   ```js ins={4,10-16}
   // 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',
   				}),
   			],
   		}),
   	],
   });
   ```

</Steps>

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](https://www.algolia.com/doc/api-reference/search-api-parameters/).

##### Additional DocSearch options

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

<Steps>

1. Create a TypeScript file exporting your DocSearch configuration.

   ```ts
   // 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`.

   ```js {11-13}
   // 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',
   				}),
   			],
   		}),
   	],
   });
   ```

</Steps>

See the [DocSearch JavaScript client API Reference](https://docsearch.algolia.com/docs/api/) 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](/guides/i18n/#translate-starlights-ui).

<Steps>

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

   ```js ins={5} ins=/{ extend: .+ }/
   // 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:

   ```json title="src/content/i18n/en.json"
   {
   	"docsearch.searchBox.resetButtonTitle": "Clear the query",
   	"docsearch.searchBox.resetButtonAriaLabel": "Clear the query",
   	"docsearch.searchBox.cancelButtonText": "Cancel",
   	"docsearch.searchBox.cancelButtonAriaLabel": "Cancel",
   	"docsearch.searchBox.searchInputLabel": "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.errorScreen.titleText": "Unable to fetch results",
   	"docsearch.errorScreen.helpText": "You might want to check your network connection.",

   	"docsearch.footer.selectText": "to select",
   	"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.closeKeyAriaLabel": "Escape key",
   	"docsearch.footer.searchByText": "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."
   }
   ```

</Steps>