Docusaurus v2 中使用 Algolia DocSearch 查找文档的便捷指南

前言

Docusaurus 是一款现代而强大，且易于使用的文档站点生成器，基于 React 技术构建，旨在为开发人员创建专业且现代化的文档站点。Algolia DocSearch 是 Algolia 提供的一个免费开源的 JavaScript 搜索库，可为您的文档站点提供强大的搜索功能，帮助用户快速查找所需信息。

安装 Algolia DocSearch

在 Docusaurus v2 中使用 Algolia DocSearch，首先需要安装 Algolia DocSearch 包。您可以使用以下命令进行安装：

npm install algoliasearch docsearch.js

安装完成后，在您的 Docusaurus 项目中创建一个新的文件 docsearch.js，并添加以下代码：

const algoliasearch = require('algoliasearch');

const client = algoliasearch('YOUR_ALGOLIA_APP_ID', 'YOUR_ALGOLIA_API_KEY');

const index = client.initIndex('YOUR_ALGOLIA_INDEX_NAME');

module.exports = {
  index,
};

将 YOUR_ALGOLIA_APP_ID 替换为您的 Algolia 应用 ID，将 YOUR_ALGOLIA_API_KEY 替换为您的 Algolia API 密钥，将 YOUR_ALGOLIA_INDEX_NAME 替换为您的 Algolia 索引名称。

配置 Algolia DocSearch

在 Docusaurus 项目的 docusaurus.config.js 文件中，添加以下配置：

module.exports = {
  // ...其他配置
  algolia: {
    apiKey: 'YOUR_ALGOLIA_API_KEY',
    appId: 'YOUR_ALGOLIA_APP_ID',
    indexName: 'YOUR_ALGOLIA_INDEX_NAME',
  },
  // ...其他配置
};

将 YOUR_ALGOLIA_API_KEY 替换为您的 Algolia API 密钥，将 YOUR_ALGOLIA_APP_ID 替换为您的 Algolia 应用 ID，将 YOUR_ALGOLIA_INDEX_NAME 替换为您的 Algolia 索引名称。

使用 Algolia DocSearch

在 Docusaurus 项目的 src 目录下，创建一个新的文件 search.js，并添加以下代码：

import { docsearchPlugin } from '@docsearch/react';
import algoliasearch from 'algoliasearch/lite';

const client = algoliasearch(
  'YOUR_ALGOLIA_APP_ID',
  'YOUR_ALGOLIA_API_KEY'
);

const searchClient = {
  ...client,
  search(requests) {
    if (requests.every(({ params }) => !params.query)) {
      return Promise.resolve({
        results: [],
      });
    }
    return client.search(requests);
  },
};

const DocSearchPlugin = docsearchPlugin({
  apiKey: 'YOUR_ALGOLIA_API_KEY',
  indexName: 'YOUR_ALGOLIA_INDEX_NAME',
  searchClient,
});

export default DocSearchPlugin;

将 YOUR_ALGOLIA_API_KEY 替换为您的 Algolia API 密钥，将 YOUR_ALGOLIA_APP_ID 替换为您的 Algolia 应用 ID，将 YOUR_ALGOLIA_INDEX_NAME 替换为您的 Algolia 索引名称。

添加搜索框

在 Docusaurus 项目的 src/components 目录下，创建一个新的文件 Search.js，并添加以下代码：

import React from 'react';
import DocSearchPlugin from './search';

const Search = () => {
  return (
    <DocSearchPlugin />
  );
};

export default Search;

在 Docusaurus 项目的 src/layout 目录下，打开 Header.js 文件，并在导航栏中添加以下代码：

import Search from '../components/Search';

// ...其他代码

export default function Header() {
  return (
    <header>
      // ...其他代码
      <Search />
    </header>
  );
}

索引文档

为了让 Algolia DocSearch 能够搜索您的文档，您需要索引您的文档。您可以使用以下命令来索引您的文档：

docusaurus-search-local --algoliaAppId YOUR_ALGOLIA_APP_ID --algoliaApiKey YOUR_ALGOLIA_API_KEY --algoliaIndexName YOUR_ALGOLIA_INDEX_NAME

将 YOUR_ALGOLIA_APP_ID 替换为您的 Algolia 应用 ID，将 YOUR_ALGOLIA_API_KEY 替换为您的 Algolia API 密钥，将 YOUR_ALGOLIA_INDEX_NAME 替换为您的 Algolia 索引名称。

结语

现在，您已经成功地在 Docusaurus v2 中集成了 Algolia DocSearch。您可以在您的文档站点上使用 Algolia DocSearch 来搜索您的文档，帮助用户快速查找所需信息。