Algolia Search

注意

如果您使用 Algolia 的免费套餐，则必须在您的搜索对话框中显示他们的徽标。

介绍

Algolia 集成会自动为文档搜索配置 Algolia Search。

它会为您的文档中的每个段落创建一个记录，这也是 Algolia 推荐的做法。

每个记录包含可搜索的属性：

属性	描述
`title`	页面标题
`section`	标题 ID（可为空）
`content`	段落内容

section 字段仅存在于标题下的段落中。标题和段落被索引为单独的记录，按页面 ID 分组。

请注意，它期望页面的 url 属性是唯一的，您不应有两个页面具有相同的 url。

设置

安装依赖：

npm install algoliasearch

在 Algolia 上注册

注册并获取您的搜索的应用程序 ID 和 API 密钥。将这些凭据存储在环境变量中。

同步搜索索引

预渲染静态路由 /static.json 以将搜索索引导出到生产构建中：

lib/export-search-indexes.ts

import { source } from '@/lib/source';
import type { DocumentRecord } from 'fumadocs-core/search/algolia';

export async function exportSearchIndexes() {
  const results: DocumentRecord[] = [];

  for (const page of source.getPages()) {
    results.push({
      _id: page.url,
      structured: page.data.structuredData,
      url: page.url,
      title: page.data.title,
      description: page.data.description,
    });
  }

  return results;
}

app/static.json/route.ts

import { exportSearchIndexes } from '@/lib/export-search-indexes';

export const revalidate = false;

export async function GET() {
  return Response.json(await exportSearchIndexes());
}

制作一个脚本来同步搜索索引：

scripts/sync-content.ts

import { algoliasearch } from 'algoliasearch';
import { sync, DocumentRecord } from 'fumadocs-core/search/algolia';
import * as fs from 'node:fs';

// 预渲染的 `static.json` 的路径，根据您的 React 框架选择一个
const filePath = {
  next: '.next/server/app/static.json.body',
  'tanstack-start': '.output/public/static.json',
  'react-router': 'build/client/static.json',
  waku: 'dist/public/static.json',
}['next'];

const content = fs.readFileSync(filePath);

const records = JSON.parse(content.toString()) as DocumentRecord[];

const client = algoliasearch('id', 'key');

// 更新索引设置并同步搜索索引
void sync(client, {
  indexName: 'document',
  documents: records,
});

现在在构建后运行脚本：

package.json

{
  "scripts": {
    "build": "... && bun ./scripts/sync-content.ts"
  }
}

工作流程

您可以手动使用脚本上传搜索索引，或者将其集成到您的 CI/CD 管道中。

搜索 UI

您可以考虑不同的选项来实现 UI：

使用 Fumadocs UI 搜索对话框。

使用内置的搜索客户端钩子构建您自己的：

import { liteClient } from 'algoliasearch/lite';
import { useDocsSearch } from 'fumadocs-core/search/client';

const client = liteClient('id', 'key');

const { search, setSearch, query } = useDocsSearch({
  type: 'algolia',
  indexName: 'document',
  client,
});

直接使用他们的官方客户端。

选项

标签过滤

要配置标签过滤，请在索引中添加 tag 值。

lib/export-search-indexes.ts

import { source } from '@/lib/source';
import type { DocumentRecord } from 'fumadocs-core/search/algolia';

export async function exportSearchIndexes() {
  const results: DocumentRecord[] = [];

  for (const page of source.getPages()) {
    results.push({
      _id: page.url,
      structured: page.data.structuredData,
      url: page.url,
      title: page.data.title,
      description: page.data.description,
      tag: '<your value>',
    });
  }

  return results;
}

并更新您的搜索客户端：

Fumadocs UI：在搜索 UI 上启用标签过滤。

搜索客户端：您可以像这样添加标签过滤：

import { useDocsSearch } from 'fumadocs-core/search/client';

const { search, setSearch, query } = useDocsSearch({
  tag: '<your tag value>',
  // ...
});

tag 字段是用于分面的属性。您也可以在 Algolia 搜索客户端上使用过滤器 tag:value。

On this page