VuePress 生态系统VuePress 生态系统
  • 主题指南
  • 默认主题
  • Hope 主题
  • Plume 主题
  • Reco 主题
  • 功能插件
  • Markdown 插件
  • 搜索插件
  • 博客插件
  • 渐进式应用插件
  • 统计分析插件
  • 搜索引擎优化插件
  • 开发插件
  • 工具插件
  • AI 插件
  • @vuepress/helper
  • English
  • 简体中文
GitHub
  • 主题指南
  • 默认主题
  • Hope 主题
  • Plume 主题
  • Reco 主题
  • 功能插件
  • Markdown 插件
  • 搜索插件
  • 博客插件
  • 渐进式应用插件
  • 统计分析插件
  • 搜索引擎优化插件
  • 开发插件
  • 工具插件
  • AI 插件
  • @vuepress/helper
  • English
  • 简体中文
GitHub
  • 搜索插件指南
  • docsearch
  • meilisearch
  • search
  • slimsearch

docsearch

@vuepress/plugin-docsearch

将 Algolia DocSearch 集成到 VuePress 中,为你的文档网站提供搜索功能。

使用方法

npm i -D @vuepress/plugin-docsearch@next
.vuepress/config.ts
import { docsearchPlugin } from '@vuepress/plugin-docsearch'

export default {
  plugins: [
    docsearchPlugin({
      // 配置项
    }),
  ],
}

获取搜索索引

你需要 提交你的网站 URL 来加入 DocSearch 项目。当你的索引成功创建后, DocSearch 团队会将 apiKey 和 indexName 发送到你的邮箱。接下来,你就可以配置该插件,在 VuePress 中启用 DocSearch 了。

或者,你也可以 运行你自己的爬虫 来创建索引,然后使用你自己的 appId, apiKey 和 indexName 来配置该插件。

官方爬虫配置示例
new Crawler({
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  rateLimit: 8,
  startUrls: [
    // 这是 Algolia 开始抓取网站的初始地址
    // 如果你的网站被分为数个独立部分,你可能需要在此设置多个入口链接
    'https://YOUR_WEBSITE_URL/',
  ],
  sitemaps: [
    // 如果你在使用 Sitemap 插件 (如: @vuepress-plugin/sitemap),你可以提供 Sitemap 链接
    'https://YOUR_WEBSITE_URL/sitemap.xml',
  ],
  ignoreCanonicalTo: false,
  exclusionPatterns: [
    // 你可以通过它阻止 Algolia 抓取某些 URL
  ],
  discoveryPatterns: [
    // 这是 Algolia 抓取 URL 的范围
    'https://YOUR_WEBSITE_URL/**',
  ],
  // 爬虫执行的计划时间,可根据文档更新频率设置
  schedule: 'at 02:00 every 1 day',
  actions: [
    // 你可以拥有多个 action,特别是你在一个域名下部署多个文档时
    {
      // 使用适当的名称为索引命名
      indexName: 'YOUR_INDEX_NAME',
      // 索引生效的路径
      pathsToMatch: ['https://YOUR_WEBSITE_URL/**'],
      // 控制 Algolia 如何抓取你的站点
      recordExtractor: ({ $, helpers }) => {
        // @vuepress/theme-default 的选项
        return helpers.docsearch({
          recordProps: {
            lvl0: {
              selectors: '.vp-sidebar-heading.active',
              defaultValue: 'Documentation',
            },
            lvl1: '[vp-content] h1',
            lvl2: '[vp-content] h2',
            lvl3: '[vp-content] h3',
            lvl4: '[vp-content] h4',
            lvl5: '[vp-content] h5',
            lvl6: '[vp-content] h6',
            content: '[vp-content] p, [vp-content] li',
          },
          indexHeadings: true,
        })
      },
    },
  ],
  initialIndexSettings: {
    // 控制索引如何被初始化,这仅当索引尚未生成时有效
    // 你可能需要在修改后手动删除并重新生成新的索引
    YOUR_INDEX_NAME: {
      attributesForFaceting: ['type', 'lang'],
      attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
      attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
      attributesToSnippet: ['content:10'],
      camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
      searchableAttributes: [
        'unordered(hierarchy_radio_camel.lvl0)',
        'unordered(hierarchy_radio.lvl0)',
        'unordered(hierarchy_radio_camel.lvl1)',
        'unordered(hierarchy_radio.lvl1)',
        'unordered(hierarchy_radio_camel.lvl2)',
        'unordered(hierarchy_radio.lvl2)',
        'unordered(hierarchy_radio_camel.lvl3)',
        'unordered(hierarchy_radio.lvl3)',
        'unordered(hierarchy_radio_camel.lvl4)',
        'unordered(hierarchy_radio.lvl4)',
        'unordered(hierarchy_radio_camel.lvl5)',
        'unordered(hierarchy_radio.lvl5)',
        'unordered(hierarchy_radio_camel.lvl6)',
        'unordered(hierarchy_radio.lvl6)',
        'unordered(hierarchy_camel.lvl0)',
        'unordered(hierarchy.lvl0)',
        'unordered(hierarchy_camel.lvl1)',
        'unordered(hierarchy.lvl1)',
        'unordered(hierarchy_camel.lvl2)',
        'unordered(hierarchy.lvl2)',
        'unordered(hierarchy_camel.lvl3)',
        'unordered(hierarchy.lvl3)',
        'unordered(hierarchy_camel.lvl4)',
        'unordered(hierarchy.lvl4)',
        'unordered(hierarchy_camel.lvl5)',
        'unordered(hierarchy.lvl5)',
        'unordered(hierarchy_camel.lvl6)',
        'unordered(hierarchy.lvl6)',
        'content',
      ],
      distinct: true,
      attributeForDistinct: 'url',
      customRanking: [
        'desc(weight.pageRank)',
        'desc(weight.level)',
        'asc(weight.position)',
      ],
      ranking: [
        'words',
        'filters',
        'typo',
        'attribute',
        'proximity',
        'exact',
        'custom',
      ],
      highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
      highlightPostTag: '</span>',
      minWordSizefor1Typo: 3,
      minWordSizefor2Typos: 7,
      allowTyposOnNumericTokens: false,
      minProximity: 1,
      ignorePlurals: true,
      advancedSyntax: true,
      attributeCriteriaComputedByMinProximity: true,
      removeWordsIfNoResults: 'allOptional',
    },
  },
})

上述 recordProps 是用于默认主题的配置,你可以根据你使用的主题来修改它们。

注意 initialIndexSettings.YOUR_INDEX_NAME.attributesForFaceting 字段必须包含 'lang',否则该插件将无法正常工作。

提示

如果你使用的不是默认主题,或者在使用 DocSearch 的时候遇到了任何问题,你也可以检查上述的爬虫配置示例,然后前往 Algolia Crawler 仓库,在你项目侧边栏中的 Editor 页面中修改你的配置。

配置项

apiKey

  • 类型: string

  • 是否必需: true

  • 详情:

    从 DocSearch 团队收到的 apiKey ,或者由你自己生成。

  • 参考:

    • DocSearch > Options > apiKey

indexName

  • 类型: string

  • 是否必需: true

  • 详情:

    从 DocSearch 团队收到的 indexName ,或者由你自己生成。

  • 参考:

    • DocSearch > Options > indexName

appId

  • 类型: string

  • 是否必需: true

  • 详情:

    用于设置你的 Application ID。

  • 参考:

    • DocSearch > Options > appId

searchParameters

  • 类型: SearchParameters

  • 详情:

    Algolia 搜索 API 参数。

  • 参考:

    • DocSearch > Options > searchParameters
    • Algolia > Search API Parameters

placeholder

  • 类型: string

  • 默认值: 'Search docs'

  • 详情:

    搜索输入框的 placeholder 属性。

  • 参考:

    • DocSearch > Options > placeholder

disableUserPersonalization

  • 类型: boolean

  • 默认值: false

  • 详情:

    是否禁用所有的个性化功能:最近的搜索、收藏的搜索结果等。

  • 参考:

    • DocSearch > Options > disableUserPersonalization

initialQuery

  • 类型: string

  • 详情:

    打开弹窗时的初始请求。

  • 参考:

    • DocSearch > Options > initialQuery

translations

  • 类型: Partial<DocSearchTranslations>

  • 详情:

    允许替换 DocSearch 按钮和弹窗内的默认文字。

  • 参考:

    • DocSearch > Options > translations

maxResultsPerGroup

  • 类型: number

  • 默认值: 5

  • 详情:

    每个组的最大结果数。

  • 参考:

    • DocSearch > Options > maxResultsPerGroup

locales

  • 类型: Record<string, DocSearchPluginOptions>

  • 详情:

    在不同 locales 下对该插件进行不同的配置。

    该插件的所有其他选项都可以在 locale 中进行配置。

  • 示例:

.vuepress/config.ts
export default {
  plugins: [
    docsearchPlugin({
      appId: '<APP_ID>',
      apiKey: '<API_KEY>',
      indexName: '<INDEX_NAME>',
      locales: {
        '/': {
          placeholder: 'Search Documentation',
          translations: {
            button: {
              buttonText: 'Search Documentation',
            },
          },
        },
        '/zh/': {
          placeholder: '搜索文档',
          translations: {
            button: {
              buttonText: '搜索文档',
            },
          },
        },
      },
    }),
  ],
}
  • 参考:
    • 指南 > 多语言支持

indexBase

  • 类型: string

  • 默认值: base

  • 详情:

    搜索索引基础路径。

    如果你需要把你的站点部署到不同的域名上,你不需要把它们全都提交到 DocSearch 上来分别生成搜索索引。你可以选择其中一个域名作为 索引域名 ,并且仅将 索引域名 提交到 DocSearch 上来爬去搜索索引。然后,你就可以在不同的部署域名下复用索引。

    如果你不同部署域名下的 base 是不一样的,你就需要将这个配置设置成 索引域名 的 base ,这样其他的部署域名就可以正确复用索引了。

injectStyles

  • 类型: boolean

  • 默认值: true

  • 详情:

    是否注入 DocSearch 的默认样式。

    如果你认为 DocSearch 的默认样式和你的站点不兼容,你可以尝试覆盖默认样式,或者将该选项设置为 false 来完全移除默认样式。

    当该选项被禁用时,你需要为 DocSearch 引入你自己的样式。同时要注意,你也无法再使用 样式 章节中提到的样式自定义能力。

客户端选项

defineDocSearchConfig

type DocSearchClientLocaleOptions = Partial<DocSearchProps>

interface DocSearchClientOptions extends DocSearchClientLocaleOptions {
  locales?: Record<string, DocSearchClientLocaleOptions>
}

const defineDocSearchConfig: (
  options: MaybeRefOrGetter<DocSearchClientOptions>,
) => void

自定义 DocSearch 选项,支持普通对象,Ref 者 Getter。

注意

为了支持 VuePress 的路由与其他优化,transformItems, hitComponent navigator 和 transformSearchClient 选项已被内部配置。直接覆盖它们可能会导致非预期行为。

如果你需要自定义它们,你可能需要先理解 VuePress 的适配 并确保不破坏它们。

样式

你可以通过 @docsearch/css 提供的 CSS 变量来自定义样式:

:root {
  --docsearch-primary-color: rgb(84, 104, 255);
  --docsearch-text-color: rgb(28, 30, 33);
  --docsearch-spacing: 12px;
  --docsearch-icon-stroke-width: 1.4;
  --docsearch-highlight-color: var(--docsearch-primary-color);
  --docsearch-muted-color: rgb(150, 159, 175);
  --docsearch-container-background: rgba(101, 108, 133, 0.8);
  --docsearch-logo-color: rgba(84, 104, 255);

  /* modal */
  --docsearch-modal-width: 560px;
  --docsearch-modal-height: 600px;
  --docsearch-modal-background: rgb(245, 246, 247);
  --docsearch-modal-shadow:
    inset 1px 1px 0 0 rgba(255, 255, 255, 0.5), 0 3px 8px 0 rgba(85, 90, 100, 1);

  /* searchbox */
  --docsearch-searchbox-height: 56px;
  --docsearch-searchbox-background: rgb(235, 237, 240);
  --docsearch-searchbox-focus-background: #fff;
  --docsearch-searchbox-shadow: inset 0 0 0 2px var(--docsearch-primary-color);

  /* hit */
  --docsearch-hit-height: 56px;
  --docsearch-hit-color: rgb(68, 73, 80);
  --docsearch-hit-active-color: #fff;
  --docsearch-hit-background: #fff;
  --docsearch-hit-shadow: 0 1px 3px 0 rgb(212, 217, 225);

  /* key */
  --docsearch-key-gradient: linear-gradient(
    -225deg,
    rgb(213, 219, 228) 0%,
    rgb(248, 248, 248) 100%
  );
  --docsearch-key-shadow:
    inset 0 -2px 0 0 rgb(205, 205, 230), inset 0 0 1px 1px #fff,
    0 1px 2px 1px rgba(30, 35, 90, 0.4);

  /* footer */
  --docsearch-footer-height: 44px;
  --docsearch-footer-background: #fff;
  --docsearch-footer-shadow:
    0 -1px 0 0 rgb(224, 227, 232), 0 -3px 6px 0 rgba(69, 98, 155, 0.12);
}

组件

  • SearchBox
在 GitHub 上编辑此页
上次更新: 2025/4/12 19:03
贡献者: Mister-Hope
上一页
搜索插件指南
下一页
meilisearch