Fumadocs

Markdown

如何撰写文档

介绍

🌐 Introduction

Fumadocs 为 MDX（一种标记语言）提供了许多实用的扩展。以下是 Fumadocs 默认 MDX 语法的简要介绍。

🌐 Fumadocs provides many useful extensions to MDX, a markup language. Here is a brief introduction to the default MDX syntax of Fumadocs.

MDX 不是 Fumadocs 唯一支持的格式。实际上，你可以使用任何渲染器，例如无头 CMS。

详情请参见 自定义内容来源。

MDX

我们推荐 MDX，这是一种带有 JSX 语法的 Markdown 超集。它允许你导入组件，并在文档中使用它们，甚至可以编写 JavaScript。

🌐 We recommend MDX, a superset of Markdown with JSX syntax. It allows you to import components, and use them in the document, or even writing JavaScript.

参见：

🌐 See:

import { Component } from './component';

<Component name="Hello" />

## Heading

### Heading

#### Heading

Hello World, **Bold**, _Italic_, ~~Hidden~~

1. First
2. Second
3. Third

- Item 1
- Item 2

> Quote here

![alt](/image.png)

| Table | Description |
| ----- | ----------- |
| Hello | World       |

前言

🌐 Frontmatter

Fumadocs 默认支持基于 YAML 的页首信息，title 在 Fumadocs 界面中表示页面标题（h1）。

🌐 Fumadocs support YAML-based frontmatter by default, title represents the page title (h1) in Fumadocs UI.

---
title: This is a document
---

...

因此，除非你有自定义的页面标题渲染逻辑，否则在编写 Markdown/MDX 时通常不会使用 h1 标题（# Heading）。

🌐 For this reason, h1 title (# Heading) is usually unused when writing Markdown/MDX unless you have custom logic for page title rendering.

在 Fumadocs MDX 中

你可以使用 schema 选项来添加前置属性。

🌐 You can use the schema option to add frontmatter properties.

🌐 Auto Links

内部链接使用你的 React 框架的 <Link /> 组件（例如 next/link）来实现预取并避免完全重新加载。

🌐 Internal links use the <Link /> component of your React framework (e.g. next/link) to allow prefetching and avoid hard-reload.

外部链接将默认获得用于安全的 rel="noreferrer noopener" target="_blank" 属性。

🌐 External links will get the default rel="noreferrer noopener" target="_blank" attributes for security.

[My Link](https://github.github.com/gfm)

This also works: https://github.github.com/gfm.

卡片

🌐 Cards

用于添加链接。

🌐 Useful for adding links.

import { HomeIcon } from 'lucide-react';

<Cards>
  <Card
    href="https://next.nodejs.cn/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating"
    title="获取、缓存和重新验证"
  >
    Learn more about caching in Next.js
  </Card>
  <Card title="href 是可选的">Learn more about `fetch` in Next.js.</Card>
  <Card icon={<HomeIcon />} href="/" title="Home">
    You can include icons too.
  </Card>
</Cards>

获取、缓存和重新验证

了解更多关于 Next.js 中的缓存

href 是可选的

了解更多关于 Next.js 中的 fetch.

主页

你也可以添加图标.

“进一步阅读”部分

🌐 "Further Reading" Section

你可以这样做：

🌐 You can do something like:

page.tsx
import { getPageTreePeers } from 'fumadocs-core/page-tree';
import { source } from '@/lib/source';

<Cards>
  {getPageTreePeers(source.getPageTree(), '/docs/my-page').map((peer) => (
    <Card key={peer.url} title={peer.name} href={peer.url}>
      {peer.description}
    </Card>
  ))}
</Cards>;

这将以卡片的形式显示同一文件夹中的其他页面。

🌐 This will show the other pages in the same folder as cards.

标注

🌐 Callouts

用于添加提示/警告，默认包含。你可以指定提示类型：

🌐 Useful for adding tips/warnings, it is included by default. You can specify the type of callout:

  • info（默认）
  • warn/warning
  • error
  • success
  • idea
<Callout>Hello World</Callout>

<Callout title="标题">Hello World</Callout>

<Callout title="标题" type="error">
  Hello World
</Callout>

<Callout title="标题" type="idea">
  Hello World
</Callout>
你好，世界

标题

你好，世界

标题

你好，世界

标题

你好，世界

标题

🌐 Headings

每个标题都会自动应用锚点，它会清理无效字符，例如空格。（例如 Hello World 转为 hello-world）

🌐 An anchor is automatically applied to each heading, it sanitizes invalid characters like spaces. (e.g. Hello World to hello-world)

# Hello `World`

目录设置

🌐 TOC Settings

目录 (TOC) 将根据标题生成，你也可以自定义标题的效果：

🌐 The table of contents (TOC) will be generated based on headings, you can also customise the effects of headings:

# 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 />

自定义锚点

🌐 Custom Anchor

你可以添加 [#slug] 来自定义标题锚点。

🌐 You can add [#slug] to customise heading anchors.

# heading [#my-heading-id]

你也可以将其与目录设置连接使用，例如：

🌐 You can also chain it with TOC settings like:

# heading [toc] [#my-heading-id]

要将人们链接到特定标题，请将标题 ID 添加到哈希片段：/page#my-heading-id。

🌐 To link people to a specific heading, add the heading id to hash fragment: /page#my-heading-id.

代码块

🌐 Codeblock

语法高亮默认使用 Rehype Code 提供支持。

🌐 Syntax Highlighting is supported by default using Rehype Code.

```js
console.log('Hello World');
```

```js title="My Title"
console.log('Hello World');
```

行号

🌐 Line Numbers

显示行号，它也适用于 Twoslash 和其他转换器。

🌐 Show line numbers, it also works with Twoslash and other transformers.

```ts twoslash lineNumbers
const a = 'Hello World';
//    ^?
console.log(a);
```

你可以设置行号的初始值。

🌐 You can set the initial value of line numbers.

```js lineNumbers=4
function main() {
  console.log('starts from 4');

  return 0;
}
```

时纪转换器

🌐 Shiki Transformers

我们支持部分 Shiki Transformers，允许你高亮/样式化特定行。

🌐 We support some of the Shiki Transformers, allowing you to highlight/style specific lines.

```tsx
// highlight a line
<div>Hello World</div> // [!code highlight]

// highlight a word
// [!code word:Fumadocs]
<div>Fumadocs</div>

// diff styles
console.log('hewwo'); // [!code --]
console.log('hello'); // [!code ++]

// focus
return new ResizeObserver(() => {}) // [!code focus]
```

标签组

🌐 Tab Groups

```ts tab="Tab 1"
console.log('A');
```

```ts tab="Tab 2"
console.log('B');
```
console.log('A');

默认情况下未启用，你可以通过配置 remark 插件在标签值中使用 MDX：

🌐 While disabled by default, you use MDX in tab values by configuring the remark plugin:

source.config.ts
import { defineConfig } from 'fumadocs-mdx/config';

export default defineConfig({
  mdxOptions: {
    remarkCodeTabOptions: {
      parseMdx: true,
    },
  },
});
```ts tab="<Building /> Tab 1"
console.log('A');
```

```ts tab="<Rocket /> Tab 2"
console.log('B');
```
console.log('A');

包含

🌐 Include

这仅在 Fumadocs MDX 上可用。

引用另一个文件（也可以是 Markdown/MDX 文档）。 在 <include> 标签中指定目标文件路径（相对于 MDX 文件本身）。

🌐 Reference another file (can also be a Markdown/MDX document). Specify the target file path in <include> tag (relative to the MDX file itself).

page.mdx
<include>./another.mdx</include>

参见 include 的其他用法。

🌐 See other usages of include.

NPM 命令

🌐 NPM Commands

用于生成使用不同包管理器安装软件包的命令。

🌐 Useful for generating commands for installing packages with different package managers.

```npm
npm i next -D
```

详情请参见 remark-npm。

🌐 See remark-npm for details.

其他组件

🌐 Other Components

你可以在 MDX 文档中配置和使用内置组件，例如标签页、手风琴和可缩放图片。

🌐 You can configure & use the built-in components in your MDX document, such as Tabs, Accordions and Zoomable Image.

附加功能

🌐 Additional Features

你可能感兴趣：

🌐 You may be interested:

数学

在 Markdown/MDX 中编写数学方程式。

Mermaid

在文档中呈现图表

Twoslash

在你的文档中使用 Typescript Twoslash

Last updated on

页面别名与页面结构

组织文档的共享约定

数学

在 Markdown/MDX 中编写数学方程式。

On this page

介绍
MDX
前言
自动链接
卡片
“进一步阅读”部分
标注
标题
目录设置
自定义锚点
代码块
行号
时纪转换器
标签组
包含
NPM 命令
其他组件
附加功能