VitePress 如何开启 algolia 搜索功能
什么是 Algolia
Algolia 是一种强大的搜索引擎,可以为你的 VitePress 网站提供搜索功能。
Algolia 注册
首先,你需要申请一个 Algolia 账号。你可以在 Algolia DocSearch 官网 申请一个免费账号。
注意事项
- 您必须是该网站的所有者,或至少有更新其内容的权限
- 你的网站必须是公开的
- 你的网站必须是一个开源项目或技术博客的技术文档,不授权于商业内容
- 你的网站必须到生产环境
注册成功后,你会收到一封邮件,里面包含了你的 Algolia API Key 和 Application ID。如下界面:
根据邮箱提示操作后,你会看到如下界面:
点击 “API Keys”, 获取你的 Algolia API Key 和 Application ID。如下界面:
Algolia 配置
// .vitepress/config.js
import { defineConfig } from "vite";
export default defineConfig({
themeConfig: {
search: {
// provider: 'local', // 可以开启本地搜索
provider: "algolia",
options: {
appId: "你的appId",
apiKey: "你的apiKey",
indexName: "你的indexName",
placeholder: "请输入关键词",
translations: {
button: {
buttonText: "请输入关键词",
},
},
},
},
},
});
// .vitepress/config.js
import { defineConfig } from "vite";
export default defineConfig({
themeConfig: {
search: {
// provider: 'local', // 可以开启本地搜索
provider: "algolia",
options: {
appId: "你的appId",
apiKey: "你的apiKey",
indexName: "你的indexName",
placeholder: "请输入关键词",
translations: {
button: {
buttonText: "请输入关键词",
},
},
},
},
},
});
配置完成后,你就可以在你的 VitePress 网站上使用 Algolia 搜索功能了。
可能遇到的问题
1. 搜索结果为空
先检查 Algolia 后台是否已经爬取了数据,如果没有爬取数据,你可以手动触发爬取数据。 Algolia Crawler 控制台,如下图:
如果爬取数据后,Algolia 后台有数据,但是在 VitePress 却仍然搜索不到任何数据。
检查是否配置了
// .vitepress/config.js
lang: "zh-CN",
// .vitepress/config.js
lang: "zh-CN",
或者
// .vitepress/config.js
locales: {
root: { label: "简体中文", lang: "zh-CN" },
},
// .vitepress/config.js
locales: {
root: { label: "简体中文", lang: "zh-CN" },
},
从 VitePress 源码中VPAlgoliaSearchBox得知,如果配置了语言,那么 Algolia 搜索的时候会带上语言参数,如果 Algolia 后台没有对应语言的数据,那么就会搜索不到数据。
searchParameters: {
facetFilters: ["lang:en-US"],
},
searchParameters: {
facetFilters: ["lang:en-US"],
},
即使手动配置了上述参数,也会搜索不到数据。原因如下:
Algolia 后台的数据是以 lang:en-US
的形式存储的,而 VitePress 搜索的时候是以 lang:zh-CN
的形式搜索的,所以 Algolia 后台没有对应的数据,所以搜索不到数据。
解决办法:
更改 Algolia 后台爬取数据规则, lang:en-US
改为 lang:zh-CN
。在Algolia Crawler 控制台,点击“Editor”,调整代码,如下图:
const records = helpers.docsearch({
recordProps: {
lvl1: ["header h1", "article h1", "main h1", "h1", "head > title"],
content: ["article p, article li", "main p, main li", "p, li"],
lvl0: {
selectors: "",
defaultValue: "Documentation",
},
lvl2: ["article h2", "main h2", "h2"],
lvl3: ["article h3", "main h3", "h3"],
lvl4: ["article h4", "main h4", "h4"],
lvl5: ["article h5", "main h5", "h5"],
lvl6: ["article h6", "main h6", "h6"],
},
aggregateContent: true,
recordVersion: "v3",
});
// add lang field
records.forEach((record) => {
record.lang = "zh-CN";
});
return records;
const records = helpers.docsearch({
recordProps: {
lvl1: ["header h1", "article h1", "main h1", "h1", "head > title"],
content: ["article p, article li", "main p, main li", "p, li"],
lvl0: {
selectors: "",
defaultValue: "Documentation",
},
lvl2: ["article h2", "main h2", "h2"],
lvl3: ["article h3", "main h3", "h3"],
lvl4: ["article h4", "main h4", "h4"],
lvl5: ["article h5", "main h5", "h5"],
lvl6: ["article h6", "main h6", "h6"],
},
aggregateContent: true,
recordVersion: "v3",
});
// add lang field
records.forEach((record) => {
record.lang = "zh-CN";
});
return records;
将 recordExtractor 内容替换上述代码块即可,lang 便可设置为 zh-CN
。