# Site Search

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`](/guides/reference-frontmatter#pagefind) to the page’s frontmatter:

```md title="src/content/docs/not-indexed.md" 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.md" 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
:::::step
Install `@astrojs/starlight-docsearch`:

::::tabs{sync="pkg"}
:::tab{title="npm"}
```sh
npm install @astrojs/starlight-docsearch
```
:::

:::tab{title="pnpm"}
```sh
pnpm add @astrojs/starlight-docsearch
```
:::

:::tab{title="Yarn"}
```sh
yarn add @astrojs/starlight-docsearch
```
:::
::::
:::::

:::step
Add DocSearch to your Starlight [`plugins`](/guides/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',
				}),
			],
		}),
	],
});
```
:::
::::::

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
:::step
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;
```
:::

:::step
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',
				}),
			],
		}),
	],
});
```
:::
::::

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/guides-i18n#translate-starlights-ui).

::::steps
:::step
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() }),
	}),
};
```
:::

:::step
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."
}
```
:::
::::

### Community search providers

[Community plugins](/guides/resources-plugins#community-plugins) can also provide alternatives to Starlight’s built-in Pagefind search provider.

#### Typesense DocSearch

The [Starlight DocSearch Typesense](https://starlight-docsearch.typesense.org/) community plugin provides an open-source and self-hostable alternative that integrates the [DocSearch](https://github.com/typesense/typesense-docsearch.js) interface with a [Typesense](https://typesense.org/) backend.

See the [“Getting Started”](https://starlight-docsearch.typesense.org/getting-started/) guide in the Starlight DocSearch Typesense documentation to learn how to use it in your project.

## Related pages

- [Starlight](../index.md)
- [Using Components](./components-using-components.md)
- [Pages](./guides-pages.md)
- [Not found](./more-404.md)
- [Configuration Reference](./reference-configuration.md)
- [Plugins and Integrations](./resources-plugins.md)
- [Start Here](./start-here-index.md)
- [Getting Started](./start-here-getting-started.md)
- [Cards](./components-cards.md)
- [Guides](./guides-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.