UI 示例
写具体文档时优先选择的 Fumadocs 官方正文组件参考。
只看官方组件
本页用来比较同一段文案适合哪种 Fumadocs 展示方式。这里不写自定义样式，不引入新的 UI 库。
官方范围
正文组织
Callout、Cards、Accordions、Tabs、Steps、Inline TOC，优先用于普通文档页。
代码和结构
Code Block、Dynamic Code Block、Files、Type Table、Zoomable Image，适合 API、目录和字段说明。
页面壳和导航
Docs、Notebook、Home、Flux 等 layout 是页面层能力，不在 MDX 正文里直接混用。
额外接入
Auto Type Table、Graph View、GitHub Info 等按需接入，避免为了示例页提前增加依赖或外部请求。
写教程时怎么选
Prop
Type
教程组合模板
快速开始
Callout 提前置条件，Steps 写主流程，Tabs 放不同客户端，success Callout 收尾。
API 参考
Callout 写认证边界，TypeTable 写字段，CodeBlockTabs 放请求示例，Cards 放相关接口。
排障教程
warn Callout 写影响，Accordions 拆原因，Steps 写检查顺序，error/success Callout 标状态。
工具接入
Files 标配置位置，Tabs 分客户端，ImageZoom 放设置截图，Cards 给下一步。
组件索引
Callout
提示、警告、错误、成功、建议，以及手动组合的 CalloutContainer。
Cards
Cards / Card：并列入口、下一步阅读、相关内容。
Accordions
Accordion / Accordions：FAQ、长答案、可选细节。
Tabs
Tabs / Tab，以及 TabsList / TabsTrigger / TabsContent 高级写法。
Steps
Steps / Step：顺序操作、流程说明、检查步骤。
Code Block
代码围栏、标题、行号、代码标签页。
Code Block (Dynamic)
DynamicCodeBlock / ServerCodeBlock：运行时或服务端生成代码块。
Files
Files / Folder / File：目录树、项目结构、路径说明。
Type Table
字段、参数、配置项、响应结构。
Auto Type Table
从 TypeScript 类型生成字段表，适合正式类型文档。
Inline TOC
页面内局部目录或长章节快速跳转。
Zoomable Image
可点击放大的图片展示。
Banner
页面或全站顶部通知。
Graph View
文档关系图，适合知识库或复杂文档网络。
GitHub Info
展示 GitHub 仓库信息。
Heading
需要显式渲染标题组件时使用。
buttonVariants
需要按钮视觉时，只使用 Fumadocs 官方按钮变体。
Layouts
DocsPage、DocsLayout、RootProvider 等页面壳。
Callout
info
普通提示，适合先读结论。
warn
风险提醒，适合不能误用的边界。
warning
warning 是 warn 的同类用法，适合保留英文 API 名称时使用。
error
错误说明，适合失败原因和不可继续的状态。
success
成功状态，适合确认某个动作已经完成。
idea
建议或候选思路，适合非强制信息。
CalloutContainer
需要手动组合标题和正文时，可以使用 CalloutContainer、CalloutTitle、CalloutDescription。
Cards
Accordions
Tabs
适合命令行、Smoke 和 README 级别说明。
适合前端、Node SDK 或 Next.js 代码片段。
适合脚本、数据处理和服务端示例。
Steps
先确定用户要做什么
流程型文案先写动作，不先讲概念。
再补必要上下文
只补完成当前动作必须知道的信息。
最后给验证方式
让用户知道怎样判断自己已经成功。
Code Block
curl https://dingjiai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_USER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"public-model","messages":[{"role":"user","content":"Hi"}]}'export function createPayload(model: string) {
return {
model,
messages: [{ role: "user", content: "Hi" }],
}
}curl https://dingjiai.com/v1/chat/completionsCode Block (Dynamic)
type Model = {id: stringowned_by: string}import { ServerCodeBlock } from "fumadocs-ui/components/codeblock.rsc"
export default function Example() {
return <ServerCodeBlock code="console.log('hi')" lang="ts" />
}Files
Type Table
Prop
Type
Auto Type Table
AutoTypeTable 适合从 TypeScript 类型自动生成字段说明。当前项目没有安装 fumadocs-typescript，所以这里先保留官方用法入口，不在普通正文里直接渲染。
import { AutoTypeTable } from "fumadocs-typescript/ui"
<AutoTypeTable path="./types.ts" name="CreateChatCompletionRequest" />Inline TOC
Zoomable Image
Banner
normal Banner 适合页面顶部通知。普通正文里少用。
rainbow Banner 适合更醒目的临时通知。
Graph View
GraphView 适合展示文档之间的引用关系。当前项目没有接入 fumadocs-ui/components/graph-view 相关能力，所以这里只记录使用场景；等确实需要知识图谱时再安装或生成，不提前堆依赖。
import { GraphView } from "fumadocs-ui/components/graph-view"
<GraphView items={[]} />Heading
Heading 渲染的三级标题
正文中的普通 Markdown 标题通常已经够用；需要显式组件时再使用 Heading。
buttonVariants
GitHub Info
GithubInfo 会读取 GitHub 仓库信息，适合确实需要展示开源仓库状态的页面。当前文档页不默认渲染它，避免示例页引入外部请求。
import { GithubInfo } from "fumadocs-ui/components/github-info"
<GithubInfo owner="fumadocs" repo="fumadocs" />Layouts
Layout 是文档站页面壳，不是普通正文组件。当前项目实际使用 Docs layout；其他 layout 等真的换页面形态时再引入。
DocsLayout
当前文档站使用的侧栏、搜索、导航和移动端布局。
DocsPage
每个文档页的页面壳，负责 TOC、正文宽度、标题描述和页脚。
NotebookLayout
更像笔记本/多栏阅读的文档布局，需要单独页面入口时再用。
HomeLayout
适合首页、营销页或非文档目录入口，不替代当前 docs 页面。
FluxLayout
另一套官方文档布局风格，只有整体视觉方向确认后才切换。
RootProvider
搜索、主题、国际化等文档根能力，由 app layout 挂载。
PageLastUpdate
有 lastModified 时展示最后更新时间。
底层 UI primitives
这些组件来自 fumadocs-ui/components/ui/*，一般由上面的内容组件和页面壳组件间接使用。只有需要写自定义 React 组件时才直接 import。
import { buttonVariants } from "fumadocs-ui/components/ui/button"
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "fumadocs-ui/components/ui/collapsible"
import { Popover, PopoverContent, PopoverTrigger } from "fumadocs-ui/components/ui/popover"
import { ScrollArea } from "fumadocs-ui/components/ui/scroll-area"
import { Tabs, TabsContent, TabsList, TabsTrigger } from "fumadocs-ui/components/ui/tabs"组件注册
import defaultMdxComponents from "fumadocs-ui/mdx"
import { Accordion, Accordions } from "fumadocs-ui/components/accordion"
import { Banner } from "fumadocs-ui/components/banner"
import { CodeBlock, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, Pre } from "fumadocs-ui/components/codeblock"
import { DynamicCodeBlock } from "fumadocs-ui/components/dynamic-codeblock"
import { File, Files, Folder } from "fumadocs-ui/components/files"
import { GithubInfo } from "fumadocs-ui/components/github-info"
import { Heading } from "fumadocs-ui/components/heading"
import { ImageZoom } from "fumadocs-ui/components/image-zoom"
import { InlineTOC } from "fumadocs-ui/components/inline-toc"
import { Step, Steps } from "fumadocs-ui/components/steps"
import { Tab, Tabs, TabsContent, TabsList, TabsTrigger } from "fumadocs-ui/components/tabs"
import { TypeTable } from "fumadocs-ui/components/type-table"
import { buttonVariants } from "fumadocs-ui/components/ui/button"最后更新于