mirror of
https://github.com/aljazceru/contextvm-docs.git
synced 2025-12-20 07:24:26 +01:00
234 lines
7.5 KiB
Markdown
234 lines
7.5 KiB
Markdown
---
|
||
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> |