Skip to content

site-search.mdx

Latest commit

 

History

History
173 lines (123 loc) · 5.38 KB

site-search.mdx

File metadata and controls

173 lines (123 loc) · 5.38 KB
title Site Search
description Learn about Starlight’s built-in site search features and how to customize them.

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

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:

---
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:

---
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 install @astrojs/starlight-docsearch
    pnpm add @astrojs/starlight-docsearch
    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.

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 { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
import { docSearchI18nSchema } from '@astrojs/starlight-docsearch/schema';

export const collections = {
	docs: defineCollection({ schema: docsSchema() }),
	i18n: defineCollection({
		type: 'data',
		schema: i18nSchema({ extend: docSearchI18nSchema() }),
	}),
};

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

    These are the English defaults used by DocSearch:

    {
	"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."
}
⚡