Orama Cloud

首先，在 Orama Cloud 上创建一个账户。

REST API

REST API 集成需要上传您的文档索引。

使用以下 schema 从 Dashboard 创建一个新的 REST API 索引：

{
  "id": "string",
  "title": "string",
  "url": "string",
  "tag": "string",
  "page_id": "string",
  "section": "string",
  "section_id": "string",
  "content": "string"
}

通过预渲染静态路由导出搜索索引。

lib/export-search-indexes.ts

import { source } from '@/lib/source';
import type { OramaDocument } from 'fumadocs-core/search/orama-cloud';

export async function exportSearchIndexes() {
  return source.getPages().map((page) => {
    return {
      id: page.url,
      structured: page.data.structuredData,
      url: page.url,
      title: page.data.title,
      description: page.data.description,
    } satisfies OramaDocument;
  });
}

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

然后，使用 dashboard 中的私有 API 密钥和索引 ID，创建一个同步搜索索引的脚本。

scripts/sync-content.ts

import { sync, type OramaDocument } from 'fumadocs-core/search/orama-cloud';
import * as fs from 'node:fs/promises';
import { CloudManager } from '@oramacloud/client';

// 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'];

async function main() {
  // private API key
  const apiKey = process.env.ORAMA_PRIVATE_API_KEY;

  if (!apiKey) {
    console.log('未找到 Orama API 密钥，跳过');
    return;
  }

  const content = await fs.readFile(filePath);
  const records = JSON.parse(content.toString()) as OramaDocument[];
  const manager = new CloudManager({ api_key: apiKey });

  await sync(manager, {
    index: '<index>',
    documents: records,
  });

  console.log(`搜索已更新：${records.length} 条记录`);
}

void main();

在生产构建后运行脚本：

package.json

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

搜索客户端

要在客户端搜索文档，请考虑：

使用 Fumadocs UI 搜索对话框。

使用 Fumadocs 的内置 hook 创建自定义搜索 UI：

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

const client = new OramaClient();

const { search, setSearch, query } = useDocsSearch({
  type: 'orama-cloud',
  client,
  params: {
    // search params
  },
});

直接使用他们的搜索客户端。

Web 爬虫

从 dashboard 创建一个 Crawler 索引，并使用 “Documentation” 预设正确配置它。
从 dashboard 复制公共 API 密钥和索引 ID

搜索客户端

与 REST API 集成相同，但确保将 index 设置为 crawler。

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

const client = new OramaClient({
  endpoint: '<endpoint_url>',
  api_key: '<api_key>',
});

const { search, setSearch, query } = useDocsSearch({
  type: 'orama-cloud',
  index: 'crawler',
  client,
  params: {
    // optional search params
  },
});

Fumadocs UI 也是如此。

REST API

搜索客户端

Web 爬虫

搜索客户端

On this page