跳转到内容

全站搜索

默认情况下,Starlight 站点提供了基于 Pagefind 的全文搜索,它是一个为静态站点的快速且低带宽的搜索工具。

启用搜索不需要配置。构建并部署你的站点,然后使用网站顶部的搜索栏来查找内容。

从搜索结果中隐藏内容

排除一个页面

要从搜索结果中排除一个页面,需要将 pagefind: false 添加到页面的 frontmatter 中:

src/content/docs/不被索引.md
---
title: 要从搜索结果中隐藏的内容
pagefind: false
---

排除页面中的一部分

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

在下面的示例中,第一个段落将显示在搜索结果中,但 <div> 的内容不会:

src/content/docs/部分索引.md
---
title: 部分索引的页面
---
这段文字会被搜索到。
<div data-pagefind-ignore>
这段文字不会被搜索到。
</div>

其他搜索供应商

Algolia DocSearch

如果你加入了 Algolia 的 DocSearch 计划并且想要用它来替代 Pagefind,你可以使用官方的 Starlight DocSearch 插件。

  1. 安装 @astrojs/starlight-docsearch:

    Terminal window
    npm install @astrojs/starlight-docsearch
  2. 把 DocSearch 加到 astro.config.mjs 里你的 Starlight plugins 配置中,并传入你的 Algolia appIdapiKeyindexName

    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: '使用 DocSearch 的网站',
    plugins: [
    starlightDocSearch({
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    }),
    ],
    }),
    ],
    });

像这样更新配置后,你站点上的搜索栏将会打开一个 Algolia 的模态框而不是默认的搜索模态框。

翻译 DocSearch UI

DocSearch 默认只提供了英语 UI 文本。 使用 Starlight 内置的国际化系统来添加你的语言的模态框 UI 的翻译。

  1. src/content/config.ts 中给 Starlight 的 i18n 内容集合定义添加 DocSearch schema:

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