Algolia 搜索

安装

🌐 Setup

安装依赖：

🌐 Install dependencies:

npm install algoliasearch

在 Algolia 注册

🌐 Sign up on Algolia

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

🌐 Sign up and obtain the app id and API keys for your search. Store these credentials in environment variables.

同步搜索索引

🌐 Sync Search Indexes

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

🌐 Pre-render a static route /static.json to export search indexes into production build:

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;
}

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

export const revalidate = false;

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

编写一个脚本来同步搜索索引：

🌐 Make a script to sync search indexes:

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

// the path of pre-rendered `static.json`, choose one according to your React framework
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');

// update the index settings and sync search indexes
void sync(client, {
  indexName: 'document',
  documents: records,
});

构建后运行脚本：

🌐 Now run the script after build:

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

工作流程

🌐 Workflow

你可以使用脚本手动上传搜索索引，或将其与你的 CI/CD 流水线集成。

🌐 You may manually upload search indexes with the script, or integrate it with your CI/CD pipeline.

搜索界面

🌐 Search UI

你可以考虑不同的方式来实现用户界面：

🌐 You can consider different options for implementing the UI:

• 使用 Fumadocs 用户界面搜索对话框。

• 使用内置的搜索客户端钩子构建你自己的功能：

  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,
  });

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

高级

🌐 Advanced

标签过滤

🌐 Tag Filter

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

🌐 To configure tag filtering, add a tag value to indexes.

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;
}

并更新你的搜索客户端：

🌐 And update your search client:

• Fumadocs 界面：在搜索界面启用 标签筛选。

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

  import { useDocsSearch } from 'fumadocs-core/search/client';
  
  const { search, setSearch, query } = useDocsSearch({
    tag: '<your tag value>',
    // ...
  });

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

🌐 The tag field is an attribute for faceting. You can also use the filter tag:value on Algolia search clients.

引擎盖下

🌐 Under the Hood

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

🌐 The Algolia Integration automatically configures Algolia Search for document search.

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

🌐 It creates a record for each paragraph in your document, it is also recommended by Algolia.

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

🌐 Each record contains searchable attributes:

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

🌐 The section field only exists in paragraphs under a heading. Headings and paragraphs are indexed as an individual record, grouped by their page ID.

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

🌐 Notice that it expects the url property of a page to be unique, you shouldn't have two pages with the same url.