内置搜索

Fumadocs 支持使用 Orama 进行文档搜索，它是默认选项，同时也是推荐选项，因为它可以自托管并且完全免费。

🌐 Fumadocs supports document search with Orama, It is the default but also the recommended option since it can be self-hosted and totally free.

安装

🌐 Setup

托管服务器以处理搜索请求。

🌐 Host the server for handling search requests.

来自来源

🌐 From Source

从源对象创建服务器。

🌐 Create the server from source object.

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

export const { GET } = createFromSource(source, {
  // https://docs.orama.com/docs/orama-js/supported-languages
  language: 'english',
});

来自搜索索引

🌐 From Search Indexes

从搜索索引创建服务器，每个索引都需要一个 structuredData 字段。

🌐 Create the server from search indexes, each index needs a structuredData field.

通常，它由你的内容来源提供（例如 Fumadocs MDX）。你也可以使用 Remark Structure 插件从 Markdown/MDX 文档中提取它。

🌐 Usually, it is provided by your content source (e.g. Fumadocs MDX). You can also extract it from Markdown/MDX document using the Remark Structure plugin.

import { source } from '@/lib/source';
import { createSearchAPI } from 'fumadocs-core/search/server';

export const { GET } = createSearchAPI('advanced', {
  language: 'english',
  indexes: source.getPages().map((page) => ({
    title: page.data.title,
    description: page.data.description,
    url: page.url,
    id: page.url,
    structuredData: page.data.structuredData,
  })),
});

搜索文档

🌐 Searching Documents

你可以使用以下方式搜索文档：

🌐 You can search documents using:

• Fumadocs 界面：开箱即用，详情请参见 搜索界面。
• 搜索客户端：

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

const client = useDocsSearch({
  type: 'fetch',
});

配置

🌐 Configurations

标签过滤

🌐 Tag Filter

支持按标签筛选结果，这对于实现类似于此文档的多文档功能非常有用。

🌐 Support filtering results by tag, it's useful for implementing multi-docs similar to this documentation.

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

const server = createFromSource(source, {
  buildIndex(page) {
    return {
      title: page.data.title,
      description: page.data.description,
      url: page.url,
      id: page.url,
      structuredData: page.data.structuredData,
      // use your desired value, like page.slugs[0]
      tag: '<value>',
    };
  },
});

并更新你的搜索客户端：

🌐 and update your search client:

• Fumadocs 界面：在搜索界面配置 标签过滤。
• 搜索客户端：向钩子传递一个标签。

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

const client = useDocsSearch({
  type: 'fetch',
  tag: '<value>',
});

静态模式

🌐 Static Mode [#static-export]

要支持在静态网站上的使用，请从搜索服务器使用 staticGET，并将路由设置为静态或预渲染。

🌐 To support usage with static site, use staticGET from search server and make the route static or pre-rendered.

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

// statically cached
export const revalidate = false;
export const { staticGET: GET } = createFromSource(source);

并更新你的搜索客户端：

🌐 and update your search clients:

• Fumadocs 界面：在搜索界面使用 静态客户端。

• 搜索客户端：使用 static 替代 fetch。

  import { useDocsSearch } from 'fumadocs-core/search/client';
  
  const client = useDocsSearch({
    type: 'static',
  });

  Prop

  Type

  type"static"

  from?string

  initOrama?function

  tag?array | string

  locale?string

国际化

🌐 Internationalization

确保你的语言在 Orama 支持的语言 列表中。

🌐 Make sure your language is on the Orama Supported Languages list.

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

const server = createFromSource(source, {
  localeMap: {
    // [locale]: Orama options
    ru: { language: 'russian' },
    en: { language: 'english' },
  },
});

对于静态模式，你应该从客户端进行配置：

🌐 For Static Mode, you should configure from client-side instead:

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

function initOrama(locale?: string) {
  return create({
    schema: { _: 'string' },
    language: locale === 'ru' ? 'russian' : 'english',
  });
}

function Search() {
  const client = useDocsSearch({
    type: 'static',
    initOrama,
  });

  // ...
}

特殊语言

🌐 Special Languages

中文和日文需要额外配置：

🌐 Chinese and Japanese require additional configurations:

npm i @orama/tokenizers

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
import { createTokenizer } from '@orama/tokenizers/mandarin';

export const { GET } = createFromSource(source, {
  localeMap: {
    // [locale]: Orama options
    cn: {
      components: {
        tokenizer: createTokenizer(),
      },
      search: {
        threshold: 0,
        tolerance: 0,
      },
    },
  },
});

并更新你的搜索客户端：

🌐 and update your search clients:

• Fumadocs UI：无需更改，Fumadocs UI 会在你正确配置 i18n 时处理此问题。
• 搜索客户端：将 locale 添加到搜索客户端，这将只允许用户搜索具有指定语言环境的页面。

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

const { search, setSearch, query } = useDocsSearch({
  type: 'fetch',
  locale: 'cn',
});

无头

🌐 Headless

你可以在其他后端（如 Express 和 Elysia）上托管搜索服务器。

🌐 You can host the search server on other backend such as Express and Elysia.

import { initAdvancedSearch } from 'fumadocs-core/search/server';

const server = initAdvancedSearch({
  // you still have to pass indexes
});

server.search('query', {
  // you can specify `locale` and `tag` here
});