文档搜索

Fumadocs UI 负责提供搜索界面的展示层，而底层搜索能力的实现说明则放在 Fumadocs Core 中。

可以先从文档搜索开始了解。

搜索界面

默认搜索对话框可通过 ⌘ K 或 Ctrl K 打开。

基础配置

搜索界面的设置统一放在根布局中的 Root Provider 上。

如果你没有提供自定义实现，Fumadocs 会默认使用由 Orama 驱动的 fetch Search Client。

空状态快捷链接

你可以给搜索弹窗补充一些自定义链接。当用户还没有输入查询内容时，这些链接会作为默认入口显示出来。

app/layout.tsx

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    links: [
      ['Home', '/'],
      ['Docs', '/docs'],
    ],
  }}
>
  {children}
</RootProvider>;

关闭搜索

如果暂时不需要文档搜索，也可以直接在 root provider 中禁用它。

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    enabled: false,
  }}
>
  {children}
</RootProvider>;

自定义热键

用于唤起搜索框的快捷键同样可以改。

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    hotKey: [
      {
        display: 'K',
        key: 'k', // key code, or a function determining whether the key is pressed
      },
    ],
  }}
>
  {children}
</RootProvider>;

标签过滤

搜索界面还可以加上过滤器 UI。不过在此之前，要先确保搜索服务端已经配置好 Tag Filter。

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      defaultTag: 'value',
      tags: [
        {
          name: 'Tag Name',
          value: 'value',
        },
      ],
    },
  }}
>
  {children}
</RootProvider>;

搜索客户端选项

你也可以把选项直接传给搜索客户端，例如修改 Orama 搜索服务所使用的 API 地址。

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      api: '/api/search/docs',
    },
  }}
>
  {children}
</RootProvider>;

替换默认对话框

如果默认搜索弹窗已经接近你的需求，可以先包一层，在外面加入自己的逻辑。

components/search.tsx

'use client';
import SearchDialog from 'fumadocs-ui/components/dialog/search-default';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';

export default function CustomDialog(props: SharedProps) {
  // your own logic here
  return <SearchDialog {...props} />;
}

要把这个自定义弹窗交给 Root Provider，需要再准备一个带 use client 的包装组件：

provider.tsx

'use client';
import { RootProvider } from 'fumadocs-ui/provider';
import dynamic from 'next/dynamic';
import type { ReactNode } from 'react';

const SearchDialog = dynamic(() => import('@/components/search')); // lazy load

export function Provider({ children }: { children: ReactNode }) {
  return (
    <RootProvider
      search={{
        SearchDialog,
      }}
    >
      {children}
    </RootProvider>
  );
}

随后把原来使用 Root Provider 的地方替换成这个包装器即可：

layout.tsx

import { Provider } from './provider';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  );
}

其他搜索方案

Algolia

完整接入流程请查看集成 Algolia 搜索。

通常我们更建议直接围绕 Algolia 官方客户端 SDK 来构建，但如果你想继续复用内置搜索弹窗，也可以接进去。

components/search.tsx

'use client';
import algo from 'algoliasearch/lite';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';
import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';

const client = algo('appId', 'apiKey');
const index = client.initIndex('indexName');

export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog index={index} {...props} />;
}

将 appId、apiKey 和 indexName 替换为你自己的值。
用新的组件替换默认搜索对话框。

Note

The built-in implementation doesn't use instant search (their official javascript client).

标签过滤

和默认客户端一样，Algolia 对话框同样支持标签过滤器。

components/search.tsx

import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';

<SearchDialog
  defaultTag="value"
  tags={[
    {
      name: 'Tag Name',
      value: 'value',
    },
  ]}
/>;

Orama Cloud

接入步骤可以参考集成 Orama Cloud。

components/search.tsx

'use client';

import { OramaClient } from '@oramacloud/client';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';
import SearchDialog from 'fumadocs-ui/components/dialog/search-orama';

const client = new OramaClient({
  endpoint: 'endpoint',
  api_key: 'apiKey',
});

export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog {...props} client={client} showOrama />;
}

将 endpoint、apiKey 替换成你自己的值。
用新的组件替换默认搜索对话框。

社区集成

社区也维护了一些额外的搜索集成方案。

Trieve Search

内置 UI 组件

如果你只想单独复用内置搜索弹窗 UI，而不想沿用默认接线方式，也可以直接使用 SearchDialog 组件。

import {
  SearchDialog,
  type SharedProps,
} from 'fumadocs-ui/components/dialog/search';

export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog {...props} />;
}

Unstable

It is an internal API, might break during iterations

Fumadocs UI 负责提供搜索界面的展示层，而底层搜索能力的实现说明则放在 Fumadocs Core 中。

可以先从文档搜索开始了解。

搜索界面

默认搜索对话框可通过 ⌘ K 或 Ctrl K 打开。

基础配置

搜索界面的设置统一放在根布局中的 Root Provider 上。

如果你没有提供自定义实现，Fumadocs 会默认使用由 Orama 驱动的 fetch Search Client。

空状态快捷链接

你可以给搜索弹窗补充一些自定义链接。当用户还没有输入查询内容时，这些链接会作为默认入口显示出来。

app/layout.tsx

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    links: [
      ['Home', '/'],
      ['Docs', '/docs'],
    ],
  }}
>
  {children}
</RootProvider>;

关闭搜索

如果暂时不需要文档搜索，也可以直接在 root provider 中禁用它。

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    enabled: false,
  }}
>
  {children}
</RootProvider>;

自定义热键

用于唤起搜索框的快捷键同样可以改。

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    hotKey: [
      {
        display: 'K',
        key: 'k', // key code, or a function determining whether the key is pressed
      },
    ],
  }}
>
  {children}
</RootProvider>;

标签过滤

搜索界面还可以加上过滤器 UI。不过在此之前，要先确保搜索服务端已经配置好 Tag Filter。

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      defaultTag: 'value',
      tags: [
        {
          name: 'Tag Name',
          value: 'value',
        },
      ],
    },
  }}
>
  {children}
</RootProvider>;

搜索客户端选项

你也可以把选项直接传给搜索客户端，例如修改 Orama 搜索服务所使用的 API 地址。

import { RootProvider } from 'fumadocs-ui/root-provider';

<RootProvider
  search={{
    options: {
      api: '/api/search/docs',
    },
  }}
>
  {children}
</RootProvider>;

替换默认对话框

如果默认搜索弹窗已经接近你的需求，可以先包一层，在外面加入自己的逻辑。

components/search.tsx

'use client';
import SearchDialog from 'fumadocs-ui/components/dialog/search-default';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';

export default function CustomDialog(props: SharedProps) {
  // your own logic here
  return <SearchDialog {...props} />;
}

要把这个自定义弹窗交给 Root Provider，需要再准备一个带 use client 的包装组件：

provider.tsx

'use client';
import { RootProvider } from 'fumadocs-ui/provider';
import dynamic from 'next/dynamic';
import type { ReactNode } from 'react';

const SearchDialog = dynamic(() => import('@/components/search')); // lazy load

export function Provider({ children }: { children: ReactNode }) {
  return (
    <RootProvider
      search={{
        SearchDialog,
      }}
    >
      {children}
    </RootProvider>
  );
}

随后把原来使用 Root Provider 的地方替换成这个包装器即可：

layout.tsx

import { Provider } from './provider';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  );
}

其他搜索方案

Algolia

完整接入流程请查看集成 Algolia 搜索。

通常我们更建议直接围绕 Algolia 官方客户端 SDK 来构建，但如果你想继续复用内置搜索弹窗，也可以接进去。

components/search.tsx

'use client';
import algo from 'algoliasearch/lite';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';
import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';

const client = algo('appId', 'apiKey');
const index = client.initIndex('indexName');

export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog index={index} {...props} />;
}

将 appId、apiKey 和 indexName 替换为你自己的值。
用新的组件替换默认搜索对话框。

Note

The built-in implementation doesn't use instant search (their official javascript client).

标签过滤

和默认客户端一样，Algolia 对话框同样支持标签过滤器。

components/search.tsx

import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';

<SearchDialog
  defaultTag="value"
  tags={[
    {
      name: 'Tag Name',
      value: 'value',
    },
  ]}
/>;

Orama Cloud

接入步骤可以参考集成 Orama Cloud。

components/search.tsx

'use client';

import { OramaClient } from '@oramacloud/client';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';
import SearchDialog from 'fumadocs-ui/components/dialog/search-orama';

const client = new OramaClient({
  endpoint: 'endpoint',
  api_key: 'apiKey',
});

export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog {...props} client={client} showOrama />;
}

将 endpoint、apiKey 替换成你自己的值。
用新的组件替换默认搜索对话框。

社区集成

社区也维护了一些额外的搜索集成方案。

Trieve Search

内置 UI 组件

如果你只想单独复用内置搜索弹窗 UI，而不想沿用默认接线方式，也可以直接使用 SearchDialog 组件。

import {
  SearchDialog,
  type SharedProps,
} from 'fumadocs-ui/components/dialog/search';

export default function CustomSearchDialog(props: SharedProps) {
  return <SearchDialog {...props} />;
}

Unstable

It is an internal API, might break during iterations

作者

分类

更多文章

Orelune塔罗系列：权杖四牌义——庆祝、稳定与归属

Orelune 上的 22 张大阿尔卡那解析

Orelune Tarot Series: The Suit of Pentacles - Work, Stability, and Lasting Growth

邮件列表

文档搜索

作者

分类

更多文章

Orelune塔罗系列：权杖四牌义——庆祝、稳定与归属

Orelune 上的 22 张大阿尔卡那解析

Orelune Tarot Series: The Suit of Pentacles - Work, Stability, and Lasting Growth

邮件列表