Skip to content

Commit 70bb066

Browse files
meteorlxymeteorlxy
committed
feat(plugin-search): add search plugin (close #35)
1 parent ade3413 commit 70bb066

30 files changed

+1075
-0
lines changed

‎docs/.vuepress/configs/sidebar/en.ts

+1
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@ export const en: SidebarConfig = {
9393
'/reference/plugin/medium-zoom.md',
9494
'/reference/plugin/nprogress.md',
9595
'/reference/plugin/register-components.md',
96+
'/reference/plugin/search.md',
9697
],
9798
},
9899
{

‎docs/.vuepress/configs/sidebar/zh.ts

+1
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ export const zh: SidebarConfig = {
9696
'/zh/reference/plugin/medium-zoom.md',
9797
'/zh/reference/plugin/nprogress.md',
9898
'/zh/reference/plugin/register-components.md',
99+
'/zh/reference/plugin/search.md',
99100
],
100101
},
101102
{

‎docs/reference/plugin/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
- [google-analytics](./google-analytics.md)
88
- [medium-zoom](./medium-zoom.md)
99
- [nprogress](./nprogress.md)
10+
- [register-components](./register-components.md)
11+
- [search](./search.md)
1012
- Syntax Highlighting
1113
- [prismjs](./prismjs.md)
1214
- [shiki](./shiki.md)

‎docs/reference/plugin/search.md

+169
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# search
2+
3+
<NpmBadge package="@vuepress/plugin-search" />
4+
5+
Provide local search to your documentation site.
6+
7+
::: tip
8+
Default theme will add search box to the navbar once you configure this plugin correctly.
9+
10+
This plugin may not be used directly in other themes, so you'd better refer to the documentation of your theme for more details.
11+
:::
12+
13+
## Local Search Index
14+
15+
This plugin will generate search index from your pages locally, and load the search index file when users enter your site. In other words, this is a lightweight built-in search which does not require any external requests.
16+
17+
However, when your site has a large number of pages, the size of search index file would be very large, which could slow down the page loading speed. In this case, we recommend you to use a more professional solution - [docsearch](./docsearch.md).
18+
19+
## Options
20+
21+
### locales
22+
23+
- Type: `Record<string, { placeholder: string }>`
24+
25+
- Details:
26+
27+
The text of the search box in different locales.
28+
29+
If this option is not specified, it will fallback to default text.
30+
31+
- Example:
32+
33+
```js
34+
module.exports = {
35+
plugins: [
36+
[
37+
'@vuepress/plugin-search',
38+
{
39+
locales: {
40+
'/': {
41+
placeholder: 'Search',
42+
},
43+
'/zh/': {
44+
placeholder: '搜索',
45+
},
46+
},
47+
},
48+
],
49+
],
50+
}
51+
```
52+
53+
- Also see:
54+
- [Guide > I18n](../../guide/i18n.md)
55+
56+
### hotKeys
57+
58+
- Type: `string[]`
59+
60+
- Default: `['s', '/']`
61+
62+
- Details:
63+
64+
Specify the [event.key](http://keycode.info/) of the hotkeys.
65+
66+
When hotkeys are pressed, the search box input will be focused.
67+
68+
Set to an empty array to disable hotkeys.
69+
70+
### maxSuggestions
71+
72+
- Type: `number`
73+
74+
- Default: `5`
75+
76+
- Details:
77+
78+
Specify the maximum number of search results.
79+
80+
### isSearchable
81+
82+
- Type: `(page: Page) => boolean`
83+
84+
- Default: `() => true`
85+
86+
- Details:
87+
88+
A function to determine whether a page should be included in the search index.
89+
90+
- Return `true` to include the page.
91+
- Return `false` to exclude the page.
92+
93+
- Example:
94+
95+
```js
96+
97+
module.exports = {
98+
plugins: [
99+
[
100+
'@vuepress/plugin-search',
101+
{
102+
// exclude the homepage
103+
isSearchable: (page) => page.path !== '/',
104+
},
105+
],
106+
],
107+
}
108+
```
109+
110+
### getExtraFields
111+
112+
- Type: `(page: Page) => string[]`
113+
114+
- Default: `() => []`
115+
116+
- Details:
117+
118+
A function to add extra fields to the search index of a page.
119+
120+
By default, this plugin will use page title and headers as the search index. This option could help you to add more searchable fields.
121+
122+
- Example:
123+
124+
```js
125+
126+
module.exports = {
127+
plugins: [
128+
[
129+
'@vuepress/plugin-search',
130+
{
131+
// allow searching the `tags` frontmatter
132+
getExtraFields: (page) => page.frontmatter.tags ?? [],
133+
},
134+
],
135+
],
136+
}
137+
```
138+
139+
## Styles
140+
141+
You can customize the style of the search box via CSS variables:
142+
143+
```css
144+
:root {
145+
--search-accent-color: #3eaf7c;
146+
--search-text-color: #2c3e50;
147+
--search-border-color: #eaecef;
148+
149+
--search-item-text-color: #5d81a5;
150+
--search-item-focus-bg-color: #f3f4f5;
151+
152+
--search-input-width: 8rem;
153+
--search-result-width: 20rem;
154+
}
155+
```
156+
157+
## Components
158+
159+
### SearchBox
160+
161+
- Details:
162+
163+
This plugin will register a `<SearchBox />` component globally, and you can use it without any props.
164+
165+
Put this component to where you want to place the search box. For example, default theme puts this component to the end of the navbar.
166+
167+
::: tip
168+
This component is mainly used for theme development. You don't need to use it directly in most cases.
169+
:::

‎docs/zh/reference/plugin/README.md

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
- [google-analytics](./google-analytics.md)
88
- [medium-zoom](./medium-zoom.md)
99
- [nprogress](./nprogress.md)
10+
- [register-components](./register-components.md)
11+
- [search](./search.md)
1012
- 语法高亮
1113
- [prismjs](./prismjs.md)
1214
- [shiki](./shiki.md)

‎docs/zh/reference/plugin/search.md

+169
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# search
2+
3+
<NpmBadge package="@vuepress/plugin-search" />
4+
5+
为你的文档网站提供本地搜索能力。
6+
7+
::: tip
8+
当你正确配置该插件后，默认主题会把搜索框添加到导航栏。
9+
10+
该插件不一定能在其他主题中直接使用，因此你应参考主题本身的文档来获取更多信息。
11+
:::
12+
13+
## 本地搜索索引
14+
15+
该插件会根据你的页面，在本地生成搜索索引，然后在用户访问站点时加载搜索索引文件。换句话说，这是一个轻量级的内置搜索能力，不会进行任何外部请求。
16+
17+
然而，当你的站点包含大量页面时，搜索索引文件也会变得非常大，它可能会拖慢你的页面加载速度。在这种情况下，我们建议你使用更成熟的解决方案 - [docsearch](./docsearch.md) 。
18+
19+
## 配置项
20+
21+
### locales
22+
23+
- 类型： `Record<string, { placeholder: string }>`
24+
25+
- 详情：
26+
27+
搜索框在不同 locales 下的文字。
28+
29+
如果没有指定该配置项，它会降级使用默认文字。
30+
31+
- 示例：
32+
33+
```js
34+
module.exports = {
35+
plugins: [
36+
[
37+
'@vuepress/plugin-search',
38+
{
39+
locales: {
40+
'/': {
41+
placeholder: 'Search',
42+
},
43+
'/zh/': {
44+
placeholder: '搜索',
45+
},
46+
},
47+
},
48+
],
49+
],
50+
}
51+
```
52+
53+
- 参考：
54+
- [指南 > 多语言支持](../../guide/i18n.md)
55+
56+
### hotKeys
57+
58+
- 类型： `string[]`
59+
60+
- 默认值： `['s', '/']`
61+
62+
- 详情：
63+
64+
指定热键的 [event.key](http://keycode.info/) 。
65+
66+
当按下热键时，搜索框会被聚焦。
67+
68+
将该配置项设为空数组可以金庸热键功能。
69+
70+
### maxSuggestions
71+
72+
- 类型： `number`
73+
74+
- 默认值： `5`
75+
76+
- 详情：
77+
78+
指定搜索结果的最大条数。
79+
80+
### isSearchable
81+
82+
- 类型： `(page: Page) => boolean`
83+
84+
- 默认值： `() => true`
85+
86+
- 详情：
87+
88+
一个函数，用于判断一个页面是否应该被包含在搜索索引中。
89+
90+
- 返回 `true` 来包含该页面。
91+
- 返回 `false` 来排除该页面。
92+
93+
- 示例：
94+
95+
```js
96+
97+
module.exports = {
98+
plugins: [
99+
[
100+
'@vuepress/plugin-search',
101+
{
102+
// 排除首页
103+
isSearchable: (page) => page.path !== '/',
104+
},
105+
],
106+
],
107+
}
108+
```
109+
110+
### getExtraFields
111+
112+
- 类型： `(page: Page) => string[]`
113+
114+
- 默认值： `() => []`
115+
116+
- 详情：
117+
118+
一个函数，用于在页面的搜索索引中添加额外字段。
119+
120+
默认情况下，该插件会将页面标题和小标题作为搜索索引。该配置项可以帮助你添加更多的可搜索字段。
121+
122+
- 示例：
123+
124+
```js
125+
126+
module.exports = {
127+
plugins: [
128+
[
129+
'@vuepress/plugin-search',
130+
{
131+
// 允许搜索 Frontmatter 中的 `tags`
132+
getExtraFields: (page) => page.frontmatter.tags ?? [],
133+
},
134+
],
135+
],
136+
}
137+
```
138+
139+
## 样式
140+
141+
你可以通过 CSS 变量来自定义搜索框的样式：
142+
143+
```css
144+
:root {
145+
--search-accent-color: #3eaf7c;
146+
--search-text-color: #2c3e50;
147+
--search-border-color: #eaecef;
148+
149+
--search-item-text-color: #5d81a5;
150+
--search-item-focus-bg-color: #f3f4f5;
151+
152+
--search-input-width: 8rem;
153+
--search-result-width: 20rem;
154+
}
155+
```
156+
157+
## 组件
158+
159+
### SearchBox
160+
161+
- 详情：
162+
163+
该插件会全局注册一个 `<SearchBox />` 组件，你可以不传入任何 Props 来使用它。
164+
165+
将该组件放置在你想要显示搜索框的地方。例如，默认主题将这个组件放在了导航栏的末尾。
166+
167+
::: tip
168+
该组件主要用于主题开发。在大多数情况下你不需要直接使用该组件。
169+
:::

0 commit comments

Comments
 (0)