232 lines
8.2 KiB
Markdown
232 lines
8.2 KiB
Markdown
---
|
||
title: 内容搜索
|
||
author: Plume Theme
|
||
createTime: 2024/03/04 09:58:39
|
||
permalink: /guide/features/content-search/
|
||
---
|
||
|
||
主题提供了两种方式支持 内容搜索。
|
||
|
||
- 本地内容搜索
|
||
- Algolia DocSearch
|
||
|
||
注意，请勿同时配置使用两种方式，同时配置时，只有 本地内容搜索 生效。
|
||
|
||
## 本地内容搜索
|
||
|
||
本地内容搜索由 [@vuepress-plume/plugin-search](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/plugins/plugin-search) 插件提供支持。
|
||
|
||
该插件使用 [minisearch](https://github.com/lucaong/minisearch) 进行内容搜索。
|
||
|
||
### 启用
|
||
|
||
主题默认 启用 本地内容搜索 功能。您也可以对其进行自定义配置。
|
||
|
||
```ts
|
||
import { defineUserConfig } from 'vuepress'
|
||
import { plumeTheme } from 'vuepress-theme-plume'
|
||
|
||
export default defineUserConfig({
|
||
theme: plumeTheme({
|
||
plugins: {
|
||
search: {
|
||
// more options
|
||
}
|
||
}
|
||
})
|
||
})
|
||
```
|
||
|
||
该插件会根据你的页面，在本地生成搜索索引，然后在用户访问站点时加载搜索索引文件。
|
||
换句话说，这是一个轻量级的内置搜索能力，不会进行任何外部请求。
|
||
|
||
然而，当你的站点包含大量页面时，搜索索引文件也会变得非常大，它可能会拖慢你的页面加载速度。在这种情况下，我们建议你使用更成熟的解决方案 - [Algolia DocSearch](#algolia-docsearch) 。
|
||
|
||
## Algolia DocSearch
|
||
|
||
使用 [Algolia DocSearch](https://docsearch.algolia.com/) 提供支持的网站内容搜索插件
|
||
|
||
### 启用
|
||
|
||
```ts
|
||
import { defineUserConfig } from 'vuepress'
|
||
import { plumeTheme } from 'vuepress-theme-plume'
|
||
|
||
export default defineUserConfig({
|
||
theme: plumeTheme({
|
||
plugins: {
|
||
docsearch: {
|
||
// more options
|
||
}
|
||
}
|
||
})
|
||
})
|
||
```
|
||
|
||
### 获取搜索索引
|
||
|
||
你需要 [提交你的网站 URL](https://docsearch.algolia.com/apply/) 来加入 DocSearch 项目。当你的索引成功创建后， DocSearch 团队会将 [apiKey](https://v2.vuepress.vuejs.org/zh/reference/plugin/docsearch.html#apikey) 和 [indexName](https://v2.vuepress.vuejs.org/zh/reference/plugin/docsearch.html#indexname) 发送到你的邮箱。接下来，你就可以配置该插件，在 VuePress 中启用 DocSearch 了。
|
||
|
||
或者，你也可以 [运行你自己的爬虫](https://docsearch.algolia.com/docs/run-your-own/) 来创建索引，然后使用你自己的 [appId](https://v2.vuepress.vuejs.org/zh/reference/plugin/docsearch.html#appId), [apiKey](https://v2.vuepress.vuejs.org/zh/reference/plugin/docsearch.html#apikey) 和 [indexName](https://v2.vuepress.vuejs.org/zh/reference/plugin/docsearch.html#indexname) 来配置该插件。
|
||
|
||
以下是本主题使用的 爬虫配置示例, 你可以前往 [Algolia Crawler](https://crawler.algolia.com/admin/crawlers/)
|
||
根据你的需求进行修改:
|
||
|
||
```ts
|
||
new Crawler({
|
||
appId: 'YOUR_APP_ID', // [!code highlight]
|
||
apiKey: 'YOUR_API_KEY', // [!code highlight]
|
||
rateLimit: 8,
|
||
startUrls: [
|
||
// 这是 Algolia 开始抓取网站的初始地址
|
||
// 如果你的网站被分为数个独立部分，你可能需要在此设置多个入口链接
|
||
'https://YOUR_WEBSITE_URL/', // [!code highlight]
|
||
],
|
||
renderJavaScript: false,
|
||
sitemaps: [
|
||
// 主题默认会生成 sitemap，这里需要替换为你的域名链接
|
||
'https://YOUR_WEBSITE_URL/sitemap.xml', // [!code highlight]
|
||
],
|
||
ignoreCanonicalTo: true,
|
||
discoveryPatterns: [
|
||
// 这是 Algolia 抓取 URL 的范围
|
||
'https://YOUR_WEBSITE_URL/**', // [!code highlight]
|
||
],
|
||
// 爬虫执行的计划时间，可根据文档更新频率设置
|
||
schedule: 'at 02:00 every 1 day',
|
||
actions: [
|
||
// 你可以拥有多个 action，特别是你在一个域名下部署多个文档时
|
||
{
|
||
// 使用适当的名称为索引命名
|
||
indexName: 'YOUR_INDEX_NAME', // [!code highlight]
|
||
// 索引生效的路径
|
||
pathsToMatch: ['https://YOUR_WEBSITE_URL/**'], // [!code highlight]
|
||
recordExtractor: ({ helpers }) => {
|
||
// vuepress-theme-plume 的选项
|
||
return helpers.docsearch({
|
||
recordProps: { // [!code highlight]
|
||
lvl1: '.plume-content h1', // [!code highlight]
|
||
content: '.plume-content p, .plume-content li', // [!code highlight]
|
||
lvl0: { // [!code highlight]
|
||
selectors: [ // [!code highlight]
|
||
'.sidebar-item.is-active p', // [!code highlight]
|
||
'.content-container .page-title', // [!code highlight]
|
||
], // [!code highlight]
|
||
defaultValue: 'Documentation', // [!code highlight]
|
||
}, // [!code highlight]
|
||
lvl2: '.plume-content h2', // [!code highlight]
|
||
lvl3: '.plume-content h3', // [!code highlight]
|
||
lvl4: '.plume-content h4', // [!code highlight]
|
||
lvl5: '.plume-content h5', // [!code highlight]
|
||
}, // [!code highlight]
|
||
indexHeadings: true, // [!code highlight]
|
||
aggregateContent: true, // [!code highlight]
|
||
recordVersion: 'v3', // [!code highlight]
|
||
})
|
||
},
|
||
},
|
||
],
|
||
initialIndexSettings: {
|
||
// 控制索引如何被初始化，这仅当索引尚未生成时有效
|
||
// 你可能需要在修改后手动删除并重新生成新的索引
|
||
YOUR_INDEX_NAME: { // [!code highlight]
|
||
attributesForFaceting: ['type', 'lang'], // [!code highlight]
|
||
attributesToRetrieve: [
|
||
'hierarchy',
|
||
'content',
|
||
'anchor',
|
||
'url',
|
||
'url_without_anchor',
|
||
'type',
|
||
],
|
||
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` 部分的配置选项用于本主题进行索引的爬取配置。
|
||
|
||
### 配置项
|
||
|
||
完整配置请查看 [文档](https://v2.vuepress.vuejs.org/zh/reference/plugin/docsearch.html#%E9%85%8D%E7%BD%AE%E9%A1%B9)
|
||
|
||
### 配置示例
|
||
|
||
以下是本主题使用的配置：
|
||
```ts
|
||
import { defineUserConfig } from 'vuepress'
|
||
import { plumeTheme } from 'vuepress-theme-plume'
|
||
|
||
export default defineUserConfig({
|
||
theme: plumeTheme({
|
||
plugins: {
|
||
docsearch: {
|
||
appId: 'YOUR_APP_ID', // [!code highlight]
|
||
apiKey: 'YOUR_API_KEY', // [!code highlight]
|
||
indexName: 'YOUR_INDEX_NAME', // [!code highlight]
|
||
}
|
||
}
|
||
})
|
||
})
|
||
```
|