feat: add new author and blog content files

- Introduced new author files for "Fox" in both English and Chinese with associated avatar images.
- Updated existing author names.
- Added new blog documentation files covering various topics, including "Fumadocs" and "Search" in both English and Chinese.
- Updated existing blog metadata, including authors and publication dates, to reflect recent changes and improve content organization.
This commit is contained in:
javayhu 2025-04-01 15:00:28 +08:00
parent a3444c334a
commit 7f4265892d
43 changed files with 1444 additions and 30 deletions

5
content/author/fox.mdx Normal file
View File

@ -0,0 +1,5 @@
---
slug: fox
name: Fox
avatar: /images/avatars/fox.png
---

View File

@ -0,0 +1,5 @@
---
slug: fox
name: Fox
avatar: /images/avatars/fox.png
---

View File

@ -1,5 +1,5 @@
---
slug: mkdirs
name: Mkdirs
name: Mkdirs模板
avatar: /images/avatars/mkdirs.png
---

View File

@ -1,5 +1,5 @@
---
slug: mksaas
name: MkSaaS
name: MkSaaS模板
avatar: /images/avatars/mksaas.png
---

View File

@ -1,11 +1,11 @@
---
title: Comparisons
description: How is Fumadocs different from other existing frameworks?
image: /images/blog/mkdirs-og.png
date: 2024-11-25T12:00:00.000Z
image: /images/blog/post-2.png
date: 2025-03-22T12:00:00.000Z
published: true
categories: [news, company]
author: mkdirs
author: fox
---
## Nextra

View File

@ -1,11 +1,11 @@
---
title: 对比
description: Fumadocs 与其他现有框架有何不同?
image: /images/blog/mkdirs-og.png
date: 2024-11-25T12:00:00.000Z
image: /images/blog/post-2.png
date: 2025-03-22T12:00:00.000Z
published: true
categories: [news, company]
author: mkdirs
author: fox
---
## Nextra

278
content/blog/fumadocs.mdx Normal file
View File

@ -0,0 +1,278 @@
---
title: Quick Start
description: Getting Started with Fumadocs
image: /images/blog/post-8.png
date: 2025-03-28T12:00:00.000Z
published: true
categories: [company, news]
author: mksaas
---
## Introduction
Fumadocs <span className='text-fd-muted-foreground text-sm'>(Foo-ma docs)</span> is a **documentation framework** based on Next.js, designed to be fast, flexible,
and composes seamlessly into Next.js App Router.
Fumadocs has different parts:
<Cards>
<Card icon={<CpuIcon className="text-purple-300" />} title='Fumadocs Core'>
Handles most of the logic, including document search, content source adapters, and Markdown extensions.
</Card>
<Card icon={<PanelsTopLeft className="text-blue-300" />} title='Fumadocs UI'>
The default theme of Fumadocs offers a beautiful look for documentation sites and interactive components.
</Card>
<Card icon={<Database />} title='Content Source'>
The source of your content, can be a CMS or local data layers like [Content Collections](https://www.content-collections.dev) and [Fumadocs MDX](/docs/mdx), the official content source.
</Card>
<Card icon={<Terminal />} title='Fumadocs CLI'>
A command line tool to install UI components and automate things, useful for customizing layouts.
</Card>
</Cards>
<Callout title="Want to learn more?">
Read our in-depth [What is Fumadocs](/docs/what-is-fumadocs) introduction.
</Callout>
### Terminology
**Markdown/MDX:** Markdown is a markup language for creating formatted text. Fumadocs supports Markdown and MDX (superset of Markdown) out-of-the-box.
Although not required, some basic knowledge of Next.js App Router would be useful for further customisations.
## Automatic Installation
A minimum version of Node.js 18 required, note that Node.js 23.1 might have problems with Next.js production build.
<Tabs groupId='package-manager' persist items={['npm', 'pnpm', 'yarn', 'bun']}>
```bash tab="npm"
npm create fumadocs-app
```
```bash tab="pnpm"
pnpm create fumadocs-app
```
```bash tab="yarn"
yarn create fumadocs-app
```
```bash tab="bun"
bun create fumadocs-app
```
</Tabs>
It will ask you the framework and content source to use, a new fumadocs app should be initialized. Now you can start hacking!
<Callout title='From Existing Codebase?'>
You can follow the [Manual Installation](/docs/manual-installation) guide to get started.
</Callout>
### Enjoy!
Create your first MDX file in the docs folder.
```mdx title="content/docs/index.mdx"
---
title: Hello World
---
## Yo what's up
```
Run the app in development mode and see http://localhost:3000/docs.
```package-install
npm run dev
```
## Explore
In the project, you can see:
- `lib/source.ts`: Code for content source adapter, [`loader()`](/docs/headless/source-api) provides an interface to interact with your content source, and assigns URL to your pages.
- `app/layout.config.tsx`: Shared options for layouts, optional but preferred to keep.
| Route | Description |
| ------------------------- | ------------------------------------------------------ |
| `app/(home)` | The route group for your landing page and other pages. |
| `app/docs` | The documentation layout and pages. |
| `app/api/search/route.ts` | The Route Handler for search. |
### Writing Content
For authoring docs, make sure to read:
<Cards>
<Card href="/docs/markdown" title="Markdown">
Fumadocs has some additional features for authoring content too.
</Card>
<Card href="/docs/navigation" title="Navigation">
Learn how to customise navigation links/sidebar items.
</Card>
</Cards>
### Content Source
Content source handles all your content, like compiling Markdown files and validating frontmatter.
<Tabs items={['Fumadocs MDX', 'Custom Source']}>
<Tab value='Fumadocs MDX'>
Read the [Introduction](/docs/mdx) to learn how it handles your content.
A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
</Tab>
<Tab value='Custom Source'>
Fumadocs is not Markdown-exclusive. For other sources like Sanity, you can build a [custom content source](/docs/headless/custom-source).
</Tab>
</Tabs>
### Customise UI
See [Customisation Guide](/docs/customisation).
## FAQ
Some common questions you may encounter.
<Accordions>
<Accordion id='fix-monorepo-styling' title="How to fix stylings not being applied in Monorepo?">
Sometimes, `fumadocs-ui` is not installed in the workspace of your Tailwind CSS configuration file. (e.g. a monorepo setup).
You have to ensure the `fumadocs-ui` package is scanned by Tailwind CSS, and give a correct relative path to `@source`.
For example, add `../../` to point to the `node_modules` folder in root workspace.
```css
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
/* [!code --] */
@source '../node_modules/fumadocs-ui/dist/**/*.js';
/* [!code ++] */
@source '../../../node_modules/fumadocs-ui/dist/**/*.js';
```
</Accordion>
<Accordion id='change-base-url' title="How to change the base route of /docs?">
You can change the base route of docs (e.g. from `/docs/page` to `/info/page`).
Since Fumadocs uses Next.js App Router, you can simply rename the route:
<Files>
<Folder name="app/docs" defaultOpen className="opacity-50" disabled>
<File name="layout.tsx" />
</Folder>
<Folder name="app/info" defaultOpen>
<File name="layout.tsx" />
</Folder>
</Files>
And tell Fumadocs to use the new route in `source.ts`:
```ts title="lib/source.ts"
import { loader } from 'fumadocs-core/source';
export const source = loader({
baseUrl: '/info',
// other options
});
```
</Accordion>
<Accordion id='dynamic-route' title="It uses Dynamic Route, will it be poor in performance?">
Next.js turns dynamic route into static routes when `generateStaticParams` is configured.
Hence, it is as fast as static pages.
You can enable Static Exports on Next.js to get a static build output. (Notice that Route Handler doesn't work with static export, you have to configure static search)
</Accordion>
<Accordion id='custom-layout-docs-page' title='How to create a page in /docs without docs layout?'>
Same as managing layouts in Next.js App Router, remove the original MDX file from content directory (`/content/docs`).
This ensures duplicated pages will not cause errors.
Now, You can add the page to another route group, which isn't a descendant of docs layout.
For example, under your `app` folder:
<Files>
<File name="(home)/docs/page.tsx" />
<Folder name="docs">
<File name="layout.tsx" />
<File name="[[...slug]]/page.tsx" />
</Folder>
</Files>
will replace the `/docs` page with your `page.tsx`.
</Accordion>
<Accordion id='multi-versions' title="How to implement docs with multi-version?">
Use a separate deployment for each version.
On Vercel, this can be done by creating another branch for a specific version on your GitHub repository.
To link to the sites of other versions, use the Links API or a custom navigation component.
</Accordion>
<Accordion id='multi-docs' title="How to implement multi-docs?">
We recommend to use [Sidebar Tabs](/docs/navigation/sidebar#sidebar-tabs).
</Accordion>
</Accordions>
## Learn More
New to here? Don't worry, we are welcome for your questions.
If you find anything confusing, please give your feedback on [Github Discussion](https://github.com/fuma-nama/fumadocs/discussions)!
<Cards>
<Card
href="/docs/static-export"
title="Configure Static Export"
description="Learn how to enable static export on your docs"
/>
<Card
href="/docs/search"
title="Customise Search"
description="Learn how to customise document search"
/>
<Card
href="/docs/theme"
title="Theming"
description="Add themes to Fumadocs UI"
/>
<Card
href="/docs/components"
title="Components"
description="See all available components to enhance your docs"
/>
</Cards>

View File

@ -0,0 +1,253 @@
---
title: 快速入门
description: Fumadocs 入门指南
image: /images/blog/post-8.png
date: 2025-03-28T12:00:00.000Z
published: true
categories: [company, news]
author: mksaas
---
## 简介
Fumadocs <span className='text-fd-muted-foreground text-sm'>(Foo-ma docs)</span> 是一个基于 Next.js 的**文档框架**,设计为快速、灵活,
并无缝集成到 Next.js App Router 中。
Fumadocs 由不同部分组成:
<Cards>
<Card icon={<CpuIcon className="text-purple-300" />} title='Fumadocs Core'>
处理大部分逻辑,包括文档搜索、内容源适配器和 Markdown 扩展。
</Card>
<Card icon={<PanelsTopLeft className="text-blue-300" />} title='Fumadocs UI'>
Fumadocs 的默认主题为文档站点提供了美观的外观和交互式组件。
</Card>
<Card icon={<Database />} title='Content Source'>
您内容的来源,可以是 CMS 或本地数据层,如 [Content Collections](https://www.content-collections.dev) 和 [Fumadocs MDX](/docs/mdx),即官方内容源。
</Card>
<Card icon={<Terminal />} title='Fumadocs CLI'>
一个命令行工具,用于安装 UI 组件和自动化操作,对于自定义布局非常有用。
</Card>
</Cards>
<Callout title="想了解更多?">
阅读我们深入的 [什么是 Fumadocs](/docs/what-is-fumadocs) 介绍。
</Callout>
### 术语
**Markdown/MDX:** Markdown 是一种用于创建格式化文本的标记语言。Fumadocs 默认支持 Markdown 和 MDXMarkdown 的超集)。
虽然不是必需的,但对 Next.js App Router 的基本了解对于进一步的自定义会很有帮助。
## 自动安装
需要 Node.js 18 或更高版本,请注意 Node.js 23.1 可能在 Next.js 生产构建中存在问题。
<Tabs groupId='package-manager' persist items={['npm', 'pnpm', 'yarn', 'bun']}>
```bash tab="npm"
npm create fumadocs-app
```
```bash tab="pnpm"
pnpm create fumadocs-app
```
```bash tab="yarn"
yarn create fumadocs-app
```
```bash tab="bun"
bun create fumadocs-app
```
</Tabs>
它会询问您要使用的框架和内容源,随后将初始化一个新的 fumadocs 应用程序。现在您可以开始动手了!
<Callout title='从现有代码库开始?'>
您可以按照 [手动安装](/docs/manual-installation) 指南开始。
</Callout>
### 尽情使用!
在 docs 文件夹中创建您的第一个 MDX 文件。
```mdx title="content/docs/index.mdx"
---
title: Hello World
---
## Yo what's up
```
在开发模式下运行应用程序并查看 http://localhost:3000/docs。
```package-install
npm run dev
```
## 探索
在项目中,您可以看到:
- `lib/source.ts`:内容源适配器的代码,[`loader()`](/docs/headless/source-api) 提供了与内容源交互的接口,并为您的页面分配 URL。
- `app/layout.config.tsx`:布局的共享选项,可选但建议保留。
| 路由 | 描述 |
| ------------------------- | -------------------------------------- |
| `app/(home)` | 您的登陆页面和其他页面的路由组。 |
| `app/docs` | 文档布局和页面。 |
| `app/api/search/route.ts` | 搜索的路由处理器。 |
### 编写内容
对于编写文档,请务必阅读:
<Cards>
<Card href="/docs/markdown" title="Markdown">
Fumadocs 还有一些额外的内容创作功能。
</Card>
<Card href="/docs/navigation" title="Navigation">
了解如何自定义导航链接/侧边栏项目。
</Card>
</Cards>
### 内容源
内容源处理您的所有内容,例如编译 Markdown 文件和验证前言。
<Tabs items={['Fumadocs MDX', 'Custom Source']}>
<Tab value='Fumadocs MDX'>
阅读 [介绍](/docs/mdx) 了解它如何处理您的内容。
项目中已包含 `source.config.ts` 配置文件,您可以自定义不同的选项,如前言模式。
</Tab>
<Tab value='Custom Source'>
Fumadocs 不仅限于 Markdown。对于其他源如 Sanity您可以构建 [自定义内容源](/docs/headless/custom-source)。
</Tab>
</Tabs>
### 自定义 UI
请参阅 [自定义指南](/docs/customisation)。
## 常见问题
您可能遇到的一些常见问题。
<Accordions>
<Accordion id='fix-monorepo-styling' title="如何修复 Monorepo 中样式不应用的问题?">
有时,`fumadocs-ui` 没有安装在您的 Tailwind CSS 配置文件的工作区中(例如,在 monorepo 设置中)。
您必须确保 Tailwind CSS 扫描 `fumadocs-ui` 包,并为 `@source` 提供正确的相对路径。
例如,添加 `../../` 指向根工作区中的 `node_modules` 文件夹。
```css
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
/* [!code --] */
@source '../node_modules/fumadocs-ui/dist/**/*.js';
/* [!code ++] */
@source '../../../node_modules/fumadocs-ui/dist/**/*.js';
```
</Accordion>
<Accordion id='change-base-url' title="如何更改 /docs 的基本路由?">
您可以更改文档的基本路由(例如,从 `/docs/page` 更改为 `/info/page`)。
由于 Fumadocs 使用 Next.js App Router您可以简单地重命名路由
<Files>
<Folder name="app/docs" defaultOpen className="opacity-50" disabled>
<File name="layout.tsx" />
</Folder>
<Folder name="app/info" defaultOpen>
<File name="layout.tsx" />
</Folder>
</Files>
并在 `source.ts` 中告诉 Fumadocs 使用新的路由:
```ts title="lib/source.ts"
import { loader } from 'fumadocs-core/source';
export const source = loader({
baseUrl: '/info',
// other options
});
```
</Accordion>
<Accordion id='dynamic-route' title="它使用动态路由,性能会很差吗?">
当配置了 `generateStaticParams` 时Next.js 会将动态路由转换为静态路由。
因此,它与静态页面一样快。
您可以在 Next.js 上启用静态导出,获得静态构建输出。(请注意,路由处理器不适用于静态导出,您必须配置静态搜索)
</Accordion>
<Accordion id='custom-layout-docs-page' title='如何在 /docs 中创建没有文档布局的页面?'>
与在 Next.js App Router 中管理布局相同,从内容目录(`/content/docs`)中删除原始 MDX 文件。
这确保重复的页面不会导致错误。
现在,您可以将页面添加到另一个路由组,该组不是文档布局的后代。
例如,在您的 `app` 文件夹下:
<Files>
<File name="(home)/docs/page.tsx" />
<Folder name="docs">
<File name="layout.tsx" />
<File name="[[...slug]]/page.tsx" />
</Folder>
</Files>
将用您的 `page.tsx` 替换 `/docs` 页面。
</Accordion>
<Accordion id='multi-versions' title="如何实现多版本文档?">
为每个版本使用单独的部署。
在 Vercel 上,可以通过在 GitHub 存储库中为特定版本创建另一个分支来实现。
要链接到其他版本的站点,请使用 Links API 或自定义导航组件。
</Accordion>
<Accordion id='multi-docs' title="如何实现多文档?">
我们建议使用 [侧边栏标签](/docs/navigation/sidebar#sidebar-tabs)。
</Accordion>
</Accordions>
## 了解更多
刚来这里?别担心,我们欢迎您的问题。

View File

@ -1,8 +1,8 @@
---
title: Internationalization
description: Support multiple languages in your documentation
image: /images/blog/mksaas-og.png
date: 2024-11-26T12:00:00.000Z
image: /images/blog/post-3.png
date: 2025-03-15T12:00:00.000Z
published: true
categories: [company, product]
author: mksaas

View File

@ -1,8 +1,8 @@
---
title: 国际化
description: 在您的文档中支持多种语言
image: /images/blog/mksaas-og.png
date: 2024-11-26T12:00:00.000Z
image: /images/blog/post-3.png
date: 2025-03-15T12:00:00.000Z
published: true
categories: [company, product]
author: mksaas

View File

@ -1,11 +1,11 @@
---
title: Manual Installation
description: Create a new fumadocs project from scratch.
image: /images/blog/mksaas-og.png
date: 2025-03-31T12:00:00.000Z
image: /images/blog/post-4.png
date: 2025-03-14T12:00:00.000Z
published: true
categories: [company, product]
author: mksaas
author: mkdirs
---
> Read the [Quick Start](/docs) guide first for basic concept.

View File

@ -1,11 +1,11 @@
---
title: 手动安装
description: 从零开始创建一个新的 Fumadocs 项目
image: /images/blog/mksaas-og.png
date: 2025-03-31T12:00:00.000Z
image: /images/blog/post-4.png
date: 2025-03-14T12:00:00.000Z
published: true
categories: [company, product]
author: mksaas
author: mkdirs
---
> 请先阅读[快速入门](/docs)指南了解基本概念。

View File

@ -1,8 +1,8 @@
---
title: Markdown
description: How to write documents
image: /images/blog/mkdirs-og.png
date: 2024-11-25T12:00:00.000Z
image: /images/blog/post-5.png
date: 2025-03-05T12:00:00.000Z
published: true
categories: [news, company]
author: mkdirs

View File

@ -1,8 +1,8 @@
---
title: Markdown
description: 如何撰写文档
image: /images/blog/mkdirs-og.png
date: 2024-11-25T12:00:00.000Z
image: /images/blog/post-5.png
date: 2025-03-05T12:00:00.000Z
published: true
categories: [news, company]
author: mkdirs

280
content/blog/search.mdx Normal file
View File

@ -0,0 +1,280 @@
---
title: Search
description: Implement document search in your docs
image: /images/blog/post-6.png
date: 2025-02-15T12:00:00.000Z
published: true
categories: [company, news]
author: mksaas
---
Fumadocs UI provides a good-looking search UI for your docs, the search functionality is instead provided and documented on Fumadocs Core.
See [Document Search](/docs/headless/search).
## Search UI
Open with <kbd>⌘</kbd> <kbd>K</kbd> or <kbd>Ctrl</kbd> <kbd>K</kbd>.
### Configurations
You can customize search UI from the [Root Provider](/docs/layouts/root-provider) component in root layout.
When not specified, it uses the Default [`fetch` Search Client](/docs/headless/search/orama) powered by Orama.
### Custom Links
Add custom link items to search dialog.
They are shown as fallbacks when the query is empty.
```tsx title="app/layout.tsx"
import { RootProvider } from 'fumadocs-ui/root-provider';
<RootProvider
search={{
links: [
['Home', '/'],
['Docs', '/docs'],
],
}}
>
{children}
</RootProvider>;
```
### Disable Search
To opt-out of document search, disable it from root provider.
```tsx
import { RootProvider } from 'fumadocs-ui/root-provider';
<RootProvider
search={{
enabled: false,
}}
>
{children}
</RootProvider>;
```
### Hot Keys
Customise the hot keys to trigger search dialog.
```tsx
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>;
```
### Tag Filter
Add UI to change filters.
Make sure to configure [Tag Filter](/docs/headless/search/orama#tag-filter) on search server first.
```tsx
import { RootProvider } from 'fumadocs-ui/root-provider';
<RootProvider
search={{
options: {
defaultTag: 'value',
tags: [
{
name: 'Tag Name',
value: 'value',
},
],
},
}}
>
{children}
</RootProvider>;
```
### Search Options
Pass options to the search client, like changing the API endpoint for Orama search server:
```tsx
import { RootProvider } from 'fumadocs-ui/root-provider';
<RootProvider
search={{
options: {
api: '/api/search/docs',
},
}}
>
{children}
</RootProvider>;
```
### Replace Search Dialog
You can replace the default Search Dialog with:
```tsx title="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} />;
}
```
To pass it to the Root Provider, you need a wrapper with `use client` directive.
```tsx title="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>
);
}
```
Use it instead of your previous Root Provider
```tsx title="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>
);
}
```
## Other Solutions
### Algolia
For the setup guide, see [Integrate Algolia Search](/docs/headless/search/algolia).
While generally we recommend building your own search with their client-side
SDK, you can also plug the built-in dialog interface.
```tsx title="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} />;
}
```
1. Replace `appId`, `apiKey` and `indexName` with your desired values.
2. [Replace the default search dialog](#replace-search-dialog) with your new component.
<Callout title="Note" className='mt-4'>
The built-in implementation doesn't use instant search (their official
javascript client).
</Callout>
#### Tag Filter
Same as default search client, you can configure [Tag Filter](/docs/headless/search/algolia#tag-filter) on the dialog.
```tsx title="components/search.tsx"
import SearchDialog from 'fumadocs-ui/components/dialog/search-algolia';
<SearchDialog
defaultTag="value"
tags={[
{
name: 'Tag Name',
value: 'value',
},
]}
/>;
```
### Orama Cloud
For the setup guide, see [Integrate Orama Cloud](/docs/headless/search/orama-cloud).
```tsx title="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 />;
}
```
1. Replace `endpoint`, `apiKey` with your desired values.
2. [Replace the default search dialog](#replace-search-dialog) with your new component.
### Community Integrations
A list of integrations maintained by community.
- [Trieve Search](/docs/headless/search/trieve)
## Built-in UI
If you want to use the built-in search dialog UI instead of building your own,
you may use the `SearchDialog` component.
```tsx
import {
SearchDialog,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
export default function CustomSearchDialog(props: SharedProps) {
return <SearchDialog {...props} />;
}
```
<Callout type="warn" title="Unstable">
It is an internal API, might break during iterations
</Callout>

252
content/blog/search.zh.mdx Normal file
View File

@ -0,0 +1,252 @@
---
title: 搜索
description: 在您的文档中实现文档搜索
image: /images/blog/post-6.png
date: 2025-02-15T12:00:00.000Z
published: true
categories: [company, news]
author: mksaas
---
Fumadocs UI 为您的文档提供了一个美观的搜索界面,而搜索功能则由 Fumadocs Core 提供和记录。
参见[文档搜索](/docs/headless/search)。
## 搜索 UI
使用 <kbd>⌘</kbd> <kbd>K</kbd> 或 <kbd>Ctrl</kbd> <kbd>K</kbd> 打开。
### 配置
您可以通过根布局中的 [Root Provider](/docs/layouts/root-provider) 组件自定义搜索 UI。
当未指定时,它使用由 Orama 提供支持的默认 [`fetch` 搜索客户端](/docs/headless/search/orama)。
### 自定义链接
向搜索对话框添加自定义链接项。
当查询为空时,它们会显示为备选项。
```tsx title="app/layout.tsx"
import { RootProvider } from 'fumadocs-ui/root-provider';
<RootProvider
search={{
links: [
['Home', '/'],
['Docs', '/docs'],
],
}}
>
{children}
</RootProvider>;
```
### 禁用搜索
要禁用文档搜索,请在根提供程序中禁用它。
```tsx
import { RootProvider } from 'fumadocs-ui/root-provider';
<RootProvider
search={{
enabled: false,
}}
>
{children}
</RootProvider>;
```
### 热键
自定义触发搜索对话框的热键。
```tsx
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 以更改过滤器。
确保首先在搜索服务器上配置[标签过滤器](/docs/headless/search/orama#tag-filter)。
```tsx
import { RootProvider } from 'fumadocs-ui/root-provider';
<RootProvider
search={{
options: {
defaultTag: 'value',
tags: [
{
name: 'Tag Name',
value: 'value',
},
],
},
}}
>
{children}
</RootProvider>;
```
### 搜索选项
向搜索客户端传递选项,例如更改 Orama 搜索服务器的 API 端点:
```tsx
import { RootProvider } from 'fumadocs-ui/root-provider';
<RootProvider
search={{
options: {
api: '/api/search/docs',
},
}}
>
{children}
</RootProvider>;
```
### 替换搜索对话框
您可以用以下内容替换默认搜索对话框:
```tsx title="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` 指令的包装器。
```tsx title="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
```tsx title="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 搜索](/docs/headless/search/algolia)。
虽然我们通常建议使用他们的客户端 SDK 构建您自己的搜索,但您也可以插入内置的对话框接口。
```tsx title="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} />;
}
```
1. 将 `appId`、`apiKey` 和 `indexName` 替换为您想要的值。
2. 用您的新组件[替换默认搜索对话框](#replace-search-dialog)。
<Callout title="注意" className='mt-4'>
内置实现不使用即时搜索(他们的官方 JavaScript 客户端)。
</Callout>
#### 标签过滤器
与默认搜索客户端相同,您可以在对话框上配置[标签过滤器](/docs/headless/search/algolia#tag-filter)。
```tsx title="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](/docs/headless/search/orama-cloud)。
```tsx title="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 />;
}
```
1. 将 `endpoint`、`apiKey` 替换为您想要的值。
2. 用您的新组件[替换默认搜索对话框](#replace-search-dialog)。

171
content/blog/theme.mdx Normal file
View File

@ -0,0 +1,171 @@
---
title: Themes
description: Add Theme to Fumadocs UI
image: /images/blog/post-7.png
date: 2025-01-15T12:00:00.000Z
published: true
categories: [product, news]
author: mkdirs
---
## Usage
Note only Tailwind CSS v4 is supported:
```css title="Tailwind CSS"
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
/* path of `fumadocs-ui` relative to the CSS file */
@source '../node_modules/fumadocs-ui/dist/**/*.js';
```
### Preflight Changes
By using the Tailwind CSS plugin, or the pre-built stylesheet, your default border, text and background
colors will be changed.
### Light/Dark Modes
Fumadocs supports light/dark modes with [`next-themes`](https://github.com/pacocoursey/next-themes), it is included in Root Provider.
See [Root Provider](/docs/layouts/root-provider#theme-provider) to learn more.
### RTL Layout
RTL (Right-to-left) layout is supported.
To enable RTL, set the `dir` prop to `rtl` in body and root provider (required for Radix UI).
```tsx
import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body dir="rtl">
<RootProvider dir="rtl">{children}</RootProvider>
</body>
</html>
);
}
```
### Prefix
Fumadocs UI has its own colors, animations, and utilities.
By default, it adds a `fd-` prefix to avoid conflicts with Shadcn UI or your own CSS variables.
You can use them without the prefix by adding some aliases:
```css title="Tailwind CSS"
@theme {
--color-primary: var(--color-fd-primary);
}
```
> You can use it with CSS media queries for responsive design.
### Layout Width
Customise the max width of docs layout with CSS Variables.
```css
:root {
--fd-layout-width: 1400px;
}
```
{/* <WidthTrigger /> */}
## Tailwind CSS Preset
The Tailwind CSS preset introduces new colors and extra utilities including `fd-steps`.
### Themes
It comes with many themes out-of-the-box, you can pick one you prefer.
```css
@import 'fumadocs-ui/css/<theme>.css';
/* Example */
@import 'fumadocs-ui/css/black.css';
```
<Tabs items={['neutral', 'black', 'vitepress', 'dusk', 'catppuccin', 'ocean', 'purple']}>
<Tab value='neutral'>
![Neutral](/images/docs/themes/neutral.png)
</Tab>
<Tab value='black'>
![Black](/images/docs/themes/black.png)
</Tab>
<Tab value='vitepress'>
![Vitepress](/images/docs/themes/vitepress.png)
</Tab>
<Tab value='dusk'>
![Dusk](/images/docs/themes/dusk.png)
</Tab>
<Tab value='Catppuccin'>
![Catppuccin](/images/docs/themes/catppuccin.png)
</Tab>
<Tab value='ocean'>
![Ocean](/images/docs/themes/ocean.png)
</Tab>
<Tab value='purple'>
![Purple](/images/docs/themes/purple.png)
</Tab>
</Tabs>
### Colors
The design system was inspired by [Shadcn UI](https://ui.shadcn.com), you can easily customize the colors using CSS variables.
```css title="global.css"
:root {
--color-fd-background: hsl(0, 0%, 100%);
}
.dark {
--color-fd-background: hsl(0, 0%, 0%);
}
```
### Typography
We have a built-in plugin forked from [Tailwind CSS Typography](https://tailwindcss.com/docs/typography-plugin).
The plugin adds a `prose` class and variants to customise it.
```tsx
<div className="prose">
<h1>Good Heading</h1>
</div>
```
> The plugin works with and only with Fumadocs UI's MDX components, it may conflict with `@tailwindcss/typography`.
> If you need to use `@tailwindcss/typography` over the default plugin, [set a class name option](https://github.com/tailwindlabs/tailwindcss-typography/blob/main/README.md#changing-the-default-class-name) to avoid conflicts.

170
content/blog/theme.zh.mdx Normal file
View File

@ -0,0 +1,170 @@
---
title: 主题
description: 为 Fumadocs UI 添加主题
image: /images/blog/post-7.png
date: 2025-01-15T12:00:00.000Z
published: true
categories: [product, news]
author: mkdirs
---
## 使用方法
注意只支持 Tailwind CSS v4
```css title="Tailwind CSS"
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
/* path of `fumadocs-ui` relative to the CSS file */
@source '../node_modules/fumadocs-ui/dist/**/*.js';
```
### 预设更改
通过使用 Tailwind CSS 插件或预构建的样式表,您的默认边框、文本和背景颜色将被更改。
### 明/暗模式
Fumadocs 通过 [`next-themes`](https://github.com/pacocoursey/next-themes) 支持明/暗模式,它包含在 Root Provider 中。
参见 [Root Provider](/docs/layouts/root-provider#theme-provider) 了解更多信息。
### RTL 布局
支持 RTL从右到左布局。
要启用 RTL请在 body 和 root providerRadix UI 需要)中将 `dir` 属性设置为 `rtl`。
```tsx
import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body dir="rtl">
<RootProvider dir="rtl">{children}</RootProvider>
</body>
</html>
);
}
```
### 前缀
Fumadocs UI 有自己的颜色、动画和工具。
默认情况下,它添加了 `fd-` 前缀,以避免与 Shadcn UI 或您自己的 CSS 变量冲突。
您可以通过添加一些别名来使用它们,而无需前缀:
```css title="Tailwind CSS"
@theme {
--color-primary: var(--color-fd-primary);
}
```
> 您可以将其与 CSS 媒体查询一起使用,实现响应式设计。
### 布局宽度
使用 CSS 变量自定义文档布局的最大宽度。
```css
:root {
--fd-layout-width: 1400px;
}
```
{/* <WidthTrigger /> */}
## Tailwind CSS 预设
Tailwind CSS 预设引入了新的颜色和额外的工具,包括 `fd-steps`。
### 主题
它开箱即用地提供了许多主题,您可以选择一个您喜欢的。
```css
@import 'fumadocs-ui/css/<theme>.css';
/* Example */
@import 'fumadocs-ui/css/black.css';
```
<Tabs items={['neutral', 'black', 'vitepress', 'dusk', 'catppuccin', 'ocean', 'purple']}>
<Tab value='neutral'>
![Neutral](/images/docs/themes/neutral.png)
</Tab>
<Tab value='black'>
![Black](/images/docs/themes/black.png)
</Tab>
<Tab value='vitepress'>
![Vitepress](/images/docs/themes/vitepress.png)
</Tab>
<Tab value='dusk'>
![Dusk](/images/docs/themes/dusk.png)
</Tab>
<Tab value='Catppuccin'>
![Catppuccin](/images/docs/themes/catppuccin.png)
</Tab>
<Tab value='ocean'>
![Ocean](/images/docs/themes/ocean.png)
</Tab>
<Tab value='purple'>
![Purple](/images/docs/themes/purple.png)
</Tab>
</Tabs>
### 颜色
设计系统的灵感来自 [Shadcn UI](https://ui.shadcn.com),您可以使用 CSS 变量轻松自定义颜色。
```css title="global.css"
:root {
--color-fd-background: hsl(0, 0%, 100%);
}
.dark {
--color-fd-background: hsl(0, 0%, 0%);
}
```
### 排版
我们有一个内置插件,它是从 [Tailwind CSS Typography](https://tailwindcss.com/docs/typography-plugin) 派生而来的。
该插件添加了一个 `prose` 类和变体来自定义它。
```tsx
<div className="prose">
<h1>Good Heading</h1>
</div>
```
> 该插件仅与 Fumadocs UI 的 MDX 组件一起工作,它可能与 `@tailwindcss/typography` 冲突。
> 如果您需要使用 `@tailwindcss/typography` 而不是默认插件,请[设置类名选项](https://github.com/tailwindlabs/tailwindcss-typography/blob/main/README.md#changing-the-default-class-name)以避免冲突。

View File

@ -1,11 +1,11 @@
---
title: What is Fumadocs
description: Introducing Fumadocs, a docs framework that you can break.
image: /images/blog/boilerplatehunt-og.png
date: 2024-11-24T12:00:00.000Z
image: /images/blog/post-1.png
date: 2025-04-01T12:00:00.000Z
published: true
categories: [company, product]
author: mksaas
author: fox
---
Fumadocs was created because I wanted a more customisable experience for building docs, to be a docs framework that is not opinionated, **a "framework" that you can break**.

View File

@ -1,11 +1,11 @@
---
title: 什么是 Fumadocs
description: 介绍 Fumadocs一个可以打破常规的文档框架
image: /images/blog/boilerplatehunt-og.png
date: 2024-11-24T12:00:00.000Z
image: /images/blog/post-1.png
date: 2025-04-01T12:00:00.000Z
published: true
categories: [company, product]
author: mksaas
author: fox
---
Fumadocs 的创建是因为我想要一种更加可定制化的文档构建体验,一个不固执己见的文档框架,**一个你可以"打破"的"框架"**。

View File

@ -73,7 +73,7 @@ Customise the max width of docs layout with CSS Variables.
}
```
<WidthTrigger />
{/* <WidthTrigger /> */}
## Tailwind CSS Preset

View File

@ -72,7 +72,7 @@ Fumadocs UI 有自己的颜色、动画和工具。
}
```
<WidthTrigger />
{/* <WidthTrigger /> */}
## Tailwind CSS 预设

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 19 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 150 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 104 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 972 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 274 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 878 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 309 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 176 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.2 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 913 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 576 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 517 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 325 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 471 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 484 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 727 KiB