Markdown 语法

简介

Fumadocs 提供了许多对 MDX (Markdown + JSX) 的有用扩展. 以下是默认 MDX 语法的简要介绍.

MDX 不是 Fumadocs 唯一支持的格式, 实际上可以使用任何渲染器 (如 headless CMS). 详见 Content Source.

MDX

推荐使用 MDX — 支持 JSX 语法的 Markdown 超集. 可以在文档中导入组件甚至编写 JavaScript.

MDX 语法参考.

GFM (GitHub Flavored Markdown) 也支持, 参见 GFM 规范.

import { Component } from './component';

<Component name="Hello" />

标题

三级标题

四级标题

Hello World, Bold, Italic, Hidden

1. First
2. Second
3. Third

• Item 1
• Item 2

Quote here

Frontmatter

Fumadocs 默认支持 YAML-based frontmatter. title 在 Fumadocs UI 中代表页面标题 (h1).

---
title: 这是文档标题
---

因此通常不需要使用一级标题 # Heading, 除非有自定义逻辑.

在 Fumadocs MDX 中, 可以使用 schema 选项添加 frontmatter 属性.

密码保护

本项目支持通过 frontmatter 为页面添加密码保护. 在 frontmatter 中添加 protected: true 即可:

---
title: 私密文档
description: 需要密码访问
protected: true
---

访问该页面时会弹出密码输入框:

• 默认密码: journal2026
• 修改密码: 设置环境变量 NEXT_PUBLIC_DOCS_PASSWORD 或编辑 src/components/protected-content.tsx 中的 AUTH_PASSWORD 常量
• 验证通过后存入 sessionStorage, 关闭标签页后失效
• 纯前端验证, 适合静态站点

自动链接

内部链接使用 React 框架的 <Link /> 组件 (如 next/link), 允许预取和避免硬刷新.

外部链接自动添加 rel="noreferrer noopener" target="_blank" 属性.

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

这也生效: https://github.github.com/gfm.

Cards

用于添加链接卡片.

import { HomeIcon } from 'lucide-react';

<Cards>
  <Card
    href="https://nextjs.org/docs"
    title="Next.js 文档"
  >
    了解更多关于 Next.js 的内容
  </Card>
  <Card title="href 是可选的">
    了解更多关于 fetch 的内容.
  </Card>
  <Card icon={<HomeIcon />} href="/" title="首页">
    可以包含图标.
  </Card>
</Cards>

Callouts (提示框)

用于添加提示/警告, 默认包含. 可指定的类型:

• info (默认)
• warn / warning
• error
• success
• idea

<Callout>Hello World</Callout>

<Callout title="标题" type="warn">
  这是一条警告
</Callout>

<Callout title="标题" type="error">
  这是一条错误
</Callout>

<Callout title="标题" type="idea">
  这是一条想法
</Callout>

标题锚点

每个标题自动生成锚点, 无效字符 (如空格) 会被自动处理 (如 Hello World → hello-world).

TOC 设置

目录 (TOC) 根据标题生成, 也可以自定义标题效果:

# 标题 [!toc]

此标题将从 TOC 中隐藏.

# 另一标题 [toc]

此标题仅在 TOC 中可见.

自定义锚点

添加 [#slug] 自定义标题锚点:

# 标题 [#my-heading-id]

也可以与 TOC 设置组合:

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

链接到特定标题: /page#my-heading-id.

代码块

语法高亮默认支持, 使用 Rehype Code.

console.log('Hello World');

console.log('Hello World');

行号

显示行号, 也支持 Twoslash 和其他转换器.

const a = 'Hello World';
console.log(a);

可以设置行号初始值:

function main() {
  console.log('starts from 4');
  return 0;
}

Shiki 转换器

支持 Shiki Transformers, 允许高亮/样式化特定行:

// highlight a line
<div>Hello World</div> 
// highlight a word
<div>Fumadocs</div>
// diff styles
console.log('hewwo'); 
console.log('hello'); 
// focus
return new ResizeObserver(() => {}) 

Tab 分组

console.log('A');

要添加持久化 ID, 在第一个代码块定义 tab-group:

console.log('A');

文件引入 (Include)

仅 Fumadocs MDX 可用. 通过 <include> 标签引用另一个文件:

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

NPM 命令

用于生成不同包管理器的安装命令:

npm i next -D

更多详情见 Fumadocs 文档.