Markdown 风格指南
MDX
我们推荐使用 MDX。它是在 Markdown 基础上扩展了 JSX 语法的超集，允许你导入组件并在文档中使用，甚至可以直接编写 JavaScript。
参见：
import { Component } from './component';
<Component name="Hello" />
## 标题
### 二级标题
#### 三级标题
你好，世界，**粗体**，_斜体_，~~隐藏~~
1. 第一项
2. 第二项
3. 第三项
- 项目 1
- 项目 2
> 此处引用
| 表格 | 说明 |
| ---- | ---- |
| 你好 | 世界 |Frontmatter
支持基于 YAML 的 frontmatter，其中 title 表示页面标题（h1）。
---
title: 这是一篇文档
---
...因此，在编写 Markdown/MDX 时通常不使用一级标题（# 标题），除非你为页面标题渲染编写了自定义逻辑。
自动链接
内部链接使用 React 框架的 <Link /> 组件（例如 next/link），以支持预取并避免整页重新加载。
出于安全考虑，外部链接会自动添加 rel="noreferrer noopener" target="_blank" 属性。
[我的链接](https://github.github.com/gfm)
这样也可以：https://github.github.com/gfm。卡片
适合用于添加链接。
import { HomeIcon } from 'lucide-react';
<Cards>
<Card
href="https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating"
title="获取、缓存和重新验证"
>
了解 Next.js 中缓存的更多内容
</Card>
<Card title="href 可选">了解 Next.js 中 `fetch` 的更多内容。</Card>
<Card icon={<HomeIcon />} href="/" title="首页">
也可以添加图标。
</Card>
</Cards>提示框
适合用于添加提示或警告，默认已包含。你可以指定提示框的类型：
info（默认）warn/warningerrorsuccessidea
<Callout>你好，世界</Callout>
<Callout title="标题" type="warn">
你好，世界
</Callout>
<Callout title="标题" type="error">
你好，世界
</Callout>
<Callout title="标题" type="idea">
你好，世界
</Callout>标题
你好，世界
标题
你好，世界
标题
你好，世界
标题
每个标题都会自动生成锚点，并清理空格等无效字符。（例如，Hello World 会转换为 hello-world）
# 你好 `World`目录设置
目录（TOC）会根据标题自动生成，你也可以自定义标题在目录中的显示效果：
# 标题 [!toc]
此标题将不会显示在目录中。
# 另一个标题 [toc]
此标题**仅**会在目录中显示，你可以用它添加额外的目录项。
就像在 React 组件中渲染的标题：
<MyComp />自定义锚点
你可以通过添加 [#slug] 来自定义标题锚点。
# 标题 [#my-heading-id]也可以与目录设置组合使用，例如：
# 标题 [toc] [#my-heading-id]若要让人直接跳转到某个标题，请在链接的哈希片段中加入该标题的 ID：/page#my-heading-id。
代码块
默认使用 Rehype Code 提供语法高亮。
```js
console.log('Hello World');
```
```js title="我的标题"
console.log('Hello World');
```行号
显示行号，也可与 Twoslash 及其他转换器配合使用。
```ts twoslash lineNumbers
const a = 'Hello World';
// ^?
console.log(a); // [!code highlight]
```还可以设置行号的起始值。
```js lineNumbers=4
function main() {
console.log('starts from 4');
return 0;
}
```Shiki 转换器
支持部分 Shiki 转换器，可用于高亮或设置特定行的样式。
```tsx
// 高亮一行
<div>Hello World</div> // [\!code highlight]
// 高亮一个单词
// [\!code word:Fumadocs]
<div>Fumadocs</div>
// 差异样式
console.log('hewwo'); // [\!code --]
console.log('hello'); // [\!code ++]
// 聚焦
return new ResizeObserver(() => {}) // [\!code focus]
```标签页组
```ts tab="标签页 1"
console.log('A');
```
```ts tab="标签页 2"
console.log('B');
```console.log('A');如需添加持久化 ID，请在第一个代码块中定义 tab-group：
```ts tab="标签页 1" tab-group="my-custom-group"
console.log('A');
```
```ts tab="标签页 2"
console.log('B');
```console.log('A');另一组：
console.log('A');在标签页组中使用 MDX
你可以在标签页标题值中使用 MDX：
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkCodeTabOptions: {
parseMdx: true,
},
},
});```ts tab="<Building /> 标签页 1"
console.log('A');
```
```ts tab="<Rocket /> 标签页 2"
console.log('B');
```console.log('A');引入
引用另一个文件（也可以是 Markdown/MDX 文档）。
在 <include> 标签中指定目标文件路径（相对于当前 MDX 文件）。
<include>./another.mdx</include>NPM 命令
适合为不同包管理器生成安装命令。
```npm
npm i next -D
```详情请参阅 remark-npm。