站点搜索

默认情况下，Starlight 站点包含由 Pagefind 提供支持的全文搜索功能，它是一个适用于静态站点的快速、低带宽的搜索工具。

启用搜索无需任何配置。构建并部署你的站点，然后使用站点标题中的搜索栏来查找内容。

在搜索结果中隐藏内容

排除一个页面

要将页面从搜索索引中排除，请将 pagefind: false 添加到页面的 frontmatter 中。

src/content/docs/not-indexed.md

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

排除页面的一部分

Pagefind 将忽略带有 data-pagefind-ignore 属性的元素内的内容。

在以下示例中，第一段将显示在搜索结果中，但 <div> 的内容不会。

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>

替代搜索提供商

Algolia DocSearch

如果你有权访问 Algolia 的 DocSearch 程序 并希望使用它来代替 Pagefind，你可以使用官方的 Starlight DocSearch 插件。

1. 安装 @astrojs/starlight-docsearch

   npm

   npm install @astrojs/starlight-docsearch

   pnpm

   pnpm add @astrojs/starlight-docsearch

   Yarn

   yarn add @astrojs/starlight-docsearch

2. 将 DocSearch 添加到 astro.config.mjs 中的 Starlight plugins 配置中，并传入你的 Algolia appId、apiKey 和 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',
           }),
         ],
       }),
     ],
   });

更新此配置后，你站点上的搜索栏现在将打开 Algolia 模态框，而不是默认的搜索模态框。

DocSearch 配置

Starlight DocSearch 插件支持使用以下内联选项自定义 DocSearch 组件：

• maxResultsPerGroup：限制每个搜索组显示的结果数。默认为 5。
• disableUserPersonalization：阻止 DocSearch 将用户的最近搜索和收藏夹保存到本地存储。默认为 false。
• insights：启用 Algolia Insights 插件并将搜索事件发送到你的 DocSearch 索引。默认为 false。
• searchParameters：一个用于自定义 Algolia 搜索参数 的对象。

其他 DocSearch 选项

需要一个单独的配置文件来将 transformItems() 或 resultsFooterComponent() 等函数选项传递给 DocSearch 组件。

1. 创建一个 TypeScript 文件来导出你的 DocSearch 配置。

   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. 在 astro.config.mjs 中将你的配置文件路径传递给 Starlight DocSearch 插件。

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

有关所有支持的选项，请参阅 DocSearch JavaScript 客户端 API 参考。

翻译 DocSearch 用户界面

默认情况下，DocSearch 仅提供英文 UI 字符串。使用 Starlight 内置的国际化系统为你的语言添加模态框 UI 的翻译。

1. 在 src/content.config.ts 中使用 DocSearch schema 扩展 Starlight 的 i18n 内容集合定义。

   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. 将翻译添加到 src/content/i18n/ 中的 JSON 文件中。

   这些是 DocSearch 使用的英文默认值：

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