使用 Markdown 与 MDX 写文档
了解 Fumadocs 中可用于文档创作的 Markdown 与 MDX 能力。
概览
Fumadocs 在 MDX 之上扩展了一组很实用的创作能力。这一页会按顺序介绍 Fumadocs UI 默认提供的 Markdown 与 MDX 写作特性。
MDX is not the only supported format of Fumadocs. In fact, you can use any renderers such as next-mdx-remote or CMS.
Markdown 基础
Fumadocs 使用的是 GFM（GitHub Flavored Markdown），它建立在 CommonMark 之上。 如果想了解完整规范，可以查看 GFM 规范。
# Heading
## Heading
### Heading
#### Heading
Hello World, **Bold**, _Italic_, ~~Hidden~~
```js
console.log('Hello World');
```
1. First
2. Second
3. Third
- Item 1
- Item 2
> Quote here
| Table | Description |
| ----- | ----------- |
| Hello | World |自动链接
站内链接会通过 next/link 渲染，因此可以获得预取能力，也能避免整页硬刷新。
而外部链接则会自动补上 rel="noreferrer noopener" target="_blank" 这些更安全的属性。
[My Link](https://github.github.com/gfm)
This also works: https://github.github.com/gfm.MDX 能力
MDX 可以理解为支持 JSX 的 Markdown。 因此你不仅能写文档正文，也能按需导入组件、直接在文档里渲染，甚至导出值。
import { Component } from './component';
<Component name="Hello" />如果想了解完整语法，可以继续阅读 MDX 语法。
卡片
卡片组件默认内置，很适合拿来组织相关文章或页面入口。
<Cards>
<Card
href="https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating"
title="Fetching, Caching, and Revalidating"
>
Learn more about caching in Next.js
</Card>
</Cards>添加图标
卡片同样支持图标。
import { HomeIcon } from 'lucide-react';
<Cards>
<Card icon={<HomeIcon />} href="/" title="Home">
Go back to home
</Card>
</Cards>不带 href 的卡片
如果只想使用视觉容器，而不希望它变成链接，href 也可以省略。
<Cards>
<Card title="Fetching, Caching, and Revalidating">
Learn more about `fetch` in Next.js.
</Card>
</Cards>Fetching, Caching, and Revalidating
Learn more about fetch in Next.js.
提示框
提示框也是默认可用的组件，适合拿来放提示、注意事项或警告信息。
<Callout>Hello World</Callout>添加标题
提示框可以单独设置一个标题。
<Callout title="Title">Hello World</Callout>Title
类型
提示框支持不同的样式类型：
info（默认）warnerror
<Callout title="Title" type="error">
Hello World
</Callout>Title
Hello World
自定义组件
更多组件和选项可以查看 所有 MDX 组件和可用选项。
标题
每个标题都会自动生成锚点，并清理掉空格等无效字符。例如 Hello World 会变成 hello-world。
# Hello `World`目录设置
目录（TOC）会基于标题自动生成，而你也可以控制某些标题在目录中的表现方式。
# Heading [!toc]
This heading will be hidden from TOC.
# Another Heading [toc]
This heading will **only** be visible in TOC, you can use it to add additional TOC items.
Like headings rendered in a React component:
<MyComp />自定义锚点
如果你想自己指定标题锚点，可以使用 [#slug]。
# heading [#my-heading-id]它也可以和目录设置一起使用：
# heading [toc] [#my-heading-id]如果要把用户链接到特定标题，直接在 URL 后面加上 hash 即可：/page#my-heading-id。
Frontmatter
Fumadocs 支持 YAML frontmatter，用于保存页面标题等公共信息。 它需要放在文档最顶部。
---
title: Hello World
---
## Titlefrontmatter 可用字段可以参考 页面约定。
代码块
语法高亮默认由 Rehype Code 提供。
```js
console.log('Hello World');
```代码块也可以加标题。
```js title="My Title"
console.log('Hello World');
```高亮行
如果要强调某一行，可以加上 [!code highlight]。
```tsx
<div>Hello World</div> // [\!code highlight]
<div>Hello World</div>
<div>Goodbye</div>
<div>Hello World</div>
```高亮单词
如果要高亮某个单词，可以使用 [!code word:<match>]。
```js
// [\!code word:config]
const config = {
reactStrictMode: true,
};
```Diff 对比
```ts
console.log('hewwo'); // [\!code --]
console.log('hello'); // [\!code ++]
```console.log('hewwo');
console.log('hello'); 标签组
代码块也能和 <Tab /> 组件组合使用。
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
<Tabs items={['Tab 1', 'Tab 2']}>
<Tab value='Tab 1'>
```ts
console.log('A');
```
</Tab>
<Tab value='Tab 2'>
```ts
console.log('B');
```
</Tab>
</Tabs>注意，您可以在 MDX 文件中添加 MDX 组件，而不必导入它们。
console.log('A');console.log('B');使用 Typescript Twoslash
Twoslash 可以让 Typescript 示例显示悬停类型信息，以及检测到的类型错误。
默认情况下未启用。参见 Twoslash。
图片
所有内置内容源都能正确处理图片。
它们会自动为 next/image 做优化。
可选能力
如果文档有需要，你还可以继续开启额外插件。
数学公式
数学公式可以通过 TeX 语法编写。
```mdx
f(x) = x * e^{2 pi i \xi x}
```f(x) = x * e^{2 pi i \xi x}启用方式请参见 Math Integration。
包安装命令
还可以为 JS/Node.js 包管理器生成安装命令代码块。
```mdx
npm i next -D
```npm i next -D启用方式请参见 Remark Install。
更多插件
其余能力可以在 Fumadocs 支持的插件列表中继续查看。
更多文章
邮件列表
加入我们的社区
订阅邮件列表，及时获取最新消息和更新