docsearch
将 Algolia DocSearch在新窗口打开 集成到 VuePress 中，为你的文档网站提供搜索功能。
提示
当你正确配置该插件后，默认主题会把 DocSearch 按钮添加到导航栏。
该插件不一定能在其他主题中直接使用，因此你应参考主题本身的文档来获取更多信息。
安装
npm i -D @vuepress/plugin-docsearch@next
获取搜索索引
你需要 提交你的网站 URL在新窗口打开 来加入 DocSearch 项目。当你的索引成功创建后， DocSearch 团队会将 apiKey 和 indexName 发送到你的邮箱。接下来，你就可以配置该插件，在 VuePress 中启用 DocSearch 了。
或者，你也可以 运行你自己的爬虫在新窗口打开 来创建索引，然后使用你自己的 appId, apiKey 和 indexName 来配置该插件。
点击查看爬虫配置示例
{
"index_name": "your_index_name",
"start_urls": [
"https://your.domain.name/"
],
"stop_urls": [],
"selectors": {
"lvl0": {
"selector": ".sidebar-heading.active",
"global": true,
"default_value": "Documentation"
},
"lvl1": ".theme-default-content h1",
"lvl2": ".theme-default-content h2",
"lvl3": ".theme-default-content h3",
"lvl4": ".theme-default-content h4",
"lvl5": ".theme-default-content h5",
"text": ".theme-default-content p, .theme-default-content li",
"lang": {
"selector": "/html/@lang",
"type": "xpath",
"global": true
}
},
"custom_settings": {
"attributesForFaceting": ["lang"]
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
上述 selectors 是用于默认主题的配置，你可以根据你使用的主题来修改它们。
注意 selectors.lang 和 custom_settings.attributesForFaceting 字段，它们是必须的，否则该插件将无法正常工作。
提示
如果你使用的不是默认主题，或者在使用 Docsearch 的时候遇到了任何问题，你也可以检查上述的爬虫配置示例，然后前往 docsearch-configs在新窗口打开 仓库，向你的网站的对应配置提交 PR 。
配置项
apiKey
类型：
string是否必需：
true详情：
从 DocSearch 团队收到的
apiKey，或者由你自己生成。参考：
indexName
类型：
string是否必需：
true详情：
从 DocSearch 团队收到的
indexName，或者由你自己生成。参考：
appId
类型：
string详情：
只有在你 运行你自己的 DocSearch 爬虫在新窗口打开 时，才需要配置该选项。用于设置你的 Application ID 。
参考：
searchParameters
类型：
Record<string, any>详情：
Algolia API 的 API 参数。
参考：
placeholder
类型：
string默认值：
'Search docs'详情：
搜索输入框的 placeholder 属性。
参考：
disableUserPersonalization
类型：
boolean默认值：
false详情：
是否禁用所有的个性化功能：最近的搜索、收藏的搜索结果等。
参考：
initialQuery
类型：
string详情：
打开弹窗时的初始请求。
参考：
locales
类型：
Record<string, DocsearchPluginOptions>详情：
在不同 locales 下对该插件进行不同的配置。
该插件的所有其他选项都可以在 locale 中进行配置。
示例：
module.exports = {
plugins: [
[
'@vuepress/docsearch',
{
apiKey: '<API_KEY>',
indexName: '<INDEX_NAME>',
locales: {
'/': {
placeholder: 'Search Documentation',
},
'/zh/': {
placeholder: '搜索文档',
},
},
},
],
],
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
- 参考：
样式
你可以通过 @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);
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
组件
Docsearch
详情：
该插件会全局注册一个
<Docsearch />组件，你可以不传入任何 Props 来使用它。将该组件放置在你想要显示 docsearch 按钮的地方。例如，默认主题将这个组件放在了导航栏的末尾。
提示
该组件主要用于主题开发。在大多数情况下你不需要直接使用该组件。