antd-mini 基于 Dumi 接入 Algolia 文档搜索实践

彧衡
672 阅读4分钟

引言

antd-mini 最近官网首页进行了升级，将 dumi 文档搜索升级成为了 algolia 提供的静态站点搜索能力，它能够帮助用户更高效地定位到想要获取的内容。下面我将简单介绍一下接入 algolia 旗下的搜索服务【DocSearch】的全过程。

image.png

DocSearch 介绍

首先这是它的官网文档，你可以从这里获取更多官网它的介绍和使用方法。下面我简单总结一下：

  • 🔍️ 它是 Algolia 公司旗下的一款专门为静态站点提供站内搜索的应用
  • 🎨 提供自动分词、高亮的搜索结果面板
  • ♻️ 提供定时抓取你的静态站点进行数据更新，默认情况每周运行一次
  • 💸 完全免费和自动化的
  • 🔥 包括 Ant Design 、Vue、Babel 等大型官网技术文档都接入了该能力

DocSearch 会抓取您的网站，将内容推送到 Algolia数据库 索引，并在您的网站上提供下拉式搜索体验。

如何接入DocSearch

网站自检

因为 Dumi 默认是 SPA 应用，这将导致 Algolia 提供的 Crawler 无法成功从你的网站爬取对应数据。因此你需要提前开启 Dumi 的 sitemap 和 ssr 能力，如下：

const config = {
  ssr: {},
  exportStatic: {},
  sitemap: {
    hostname: 'https://mini.ant.design',
  },
}

开启后再构建静态站点后，你可以发现除 index.html 外的页面也都会返回单独的 html 了，并且每个 html 下 <div id="root" /> 这个根节点也会提前在服务端渲染出对应的节点后在返回了。

image.png

至此，你的站点就已经满足 Crawler 的一个前提要求了，此外你还需要满足以下条件：

  • 🔨 你必须是站点的拥有者，或者有能力去更新站点内容
  • 🌐 你的站点必须是在公网条件下可访问，内网环境下你需要自己部署定时爬虫服务。
  • 📄 你的站点必须是文档站点，个人博客或商用网站不可以
  • 🧑‍💻 你的站点要有渲染内容（开启ssr即可）

申请接入

首页你可以找到 docSearch 的 github 仓库，README 会提示你去申请使用 DocSearch 的链接，点击后你会进入到以下页面

image.png

你需要填写你的可访问网站地址、邮箱以及github仓库，完成填写后你就需要等待 docSearch 官网的第一封邮件了。

image.png

大约2-3天你会收到来自官网的邮件，内容大致就是确认你是否是站点的拥有者，或者有能力去更新站点内容，你需要对邮件进行回复。

再过大概2-3天你就会收到关于你的站点接入的代码块，其中包括你的 appId、apiKey 和 indexName 等。

image.png

dumi 配置

因为 Dumi 内置了 Algolia 的这块能力，因此你只需要在你项目的 config.ts 中开启 algolia 能力并填入对应字段内容即可。

{
  algolia: {
    appId: 'yourappid',
    apiKey: 'yourapikey',
    indexName: 'mini-ant',
  }
}

至此你的站点就完成了 DocSearch 的接入和配置流程了，这个时候你可能会发现你的搜索没有内容，这个时候需要等待最后一封邮件。

image.png

这个时候表示爬虫已经完成对你的站点进行了抓取，并把相应内容存到对应 index 下去了，如果你发现这里 Total 太少或者为 0， 你就需要去检查你的网站是否开启了 SSR 了。

内容更新

爬虫默认每周会对你的网站抓取一次，当你的网站文档更新后，你想实时更新文档，你可以去官网控制台手动执行脚本进行更新。

image.png

你也可以在控制台管理你的搜索数据

image.png

效果预览

当以上流程都完成后，你就可以在你的站点上（本地也可以）体验搜索到极佳的搜索体验了

  • 首页

image.png

  • 内页

image.png

个性化搜索

当你需要完全抛弃 dumi 提供的文档搜索能力，而采用 docSearch 能力，你可以通过 npm 包的形式在 react 中使用，通过这种方式你可以使用所有的 api 而不需要受 dumi 的限制。

import { DocSearch } from '@docsearch/react';
import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      indexName="YOUR_INDEX_NAME"
      apiKey="YOUR_SEARCH_API_KEY"
    />
  );
}

export default App;

首次查询优化

像 ant design 的搜索面板在首次搜索的时候可能会无法唤起，通过将下面的 link 内容添加到网站 head 上，就可以在进入的时候提示浏览器从 algolia 加载数据，并允许它与连接到 DocSearch 服务集群，使它在第一次查询的时候更快。

<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" />

在 dumi 里面需要进行如下配置即可

links: [
  {
    rel: 'preconnect',
    href: 'https://你的APPID-dsn.algolia.net'
  }
],

Dumi 增强

目前dumi 在 config.ts 中只支持了 appId、apiKey、indexName 和 debug 四个配置，需要进行相应增强，对应代码。

结尾

文章的最后 antd-mini 期待大家的使用和 star。

avatar
文章
阅读
粉丝