.webp)
MDX 样式和组件使用展示
Fumadocs 与 shadcn/ui 在 Leo’s Desk 文章里的常用写法、展示效果和避坑说明。
这是一页内部测试文档，用来展示 Fumadocs MDX 和 shadcn/ui 组件在文章里的常见用法。 后续写文章时，可以直接复制本页里的结构。
一、基础 Markdown 样式
1. 标题层级
正文里不要再写一级标题 #，因为页面标题已经由 frontmatter 里的 title 生成。
文章正文建议从 ## 开始：
## 一级章节
### 二级小节
#### 三级说明2. 普通段落
普通段落直接写文字即可。段落之间空一行。
学习不是把信息装进脑子，而是通过经历、练习和反馈，改变自己理解世界和处理问题的方式。
3. 强调和行内代码
可以用 加粗 强调关键判断。
可以用 inline code 标记文件名、命令、变量名或组件名。
例如：
- 文件路径：
content/zh/xuexi-fangfa/what-is-learning.mdx - 组件名：
Accordion - 命令：
pnpm dev
4. 引用块
引用块适合放题记、提醒、定义、来源说明。 不适合放太长的大段正文。
5. 分割线
分割线适合隔开正文和非正文内容。
---效果如下：
二、列表、任务和表格
1. 无序列表
- 学习不是上课
- 学习不是记笔记
- 学习不是刷题
- 学习是改变判断和行动
2. 有序列表
- 先尝试
- 暴露问题
- 得到反馈
- 修正
- 再尝试
3. 任务清单
- 写完正文
- 添加来源卡
- 检查 MDX 编译
- 发布到网站
4. 表格
| 场景 | 不推荐写法 | 推荐写法 |
|---|---|---|
| 判断学习效果 | 我学了很久 | 我下次能不能做得不同 |
| 整理错题 | 抄答案 | 找错误判断 |
| 写来源卡 | 堆文献 | 说明支撑了正文哪里 |
三、代码块写法
1. 普通代码块
代码块只用于展示代码，不要把整段 MDX 组件包进代码块，否则组件会被当成纯文本显示。
export function Hello() {
return <div>Hello Leo’s Desk</div>;
}2. 终端命令
pnpm devpnpm build3. 最容易犯的错误
下面这种写法只适合展示代码，不能直接用于让组件生效：
```mdx
<Accordions type="multiple">
<Accordion title="来源卡 01">内容</Accordion>
</Accordions>
```如果你想让组件真的渲染出来，就不要用三个反引号包住它，要直接写：
<Accordions type="multiple">
<Accordion title="来源卡 01">内容</Accordion>
</Accordions>四、Fumadocs Accordion 折叠区
适合放：
- 来源卡
- FAQ
- 非正文说明
- 后续选题
- 版本记录
- 长列表内容
推荐写法
<Accordions type="multiple">
<Accordion title="来源卡 01：学习的基本定义" id="source-learning-definition">
**核心来源：** APA Dictionary of Psychology, “Learning”。
**支撑观点：** 学习通常指个体在练习、观察或其他经验之后获得新的信息、行为或能力。
**本文用法：** 支撑“学习真正发生的标志是改变”。
</Accordion>
</Accordions>五、Fumadocs Tabs 标签页
适合放：
- 多种写法对比
- GPT / Claude / Cursor prompt 对比
- Windows / macOS 操作对比
- 正文版 / 精简版 / MDX 版
学习不是把信息装进脑子，而是你和世界交手之后，变得更会应对世界。
适合直接放在文章里。
**学习不是把信息装进脑子，而是你和世界交手之后，变得更会应对世界。**适合展示给自己或 Cursor 看。
Tabs 里面可以放 Markdown，也可以放代码块。
但不要在 Tab 内部写过度复杂的 JSX 嵌套。
六、shadcn/ui Badge 标签
适合放：
- 文章状态
- 难度
- 分类
- 适用对象
- 推荐程度
Badge 示例代码
<div className="flex flex-wrap gap-2">
<Badge>总纲文章</Badge>
<Badge variant="secondary">学习方法</Badge>
<Badge variant="outline">适合收藏</Badge>
<Badge variant="destructive">待验证</Badge>
</div>七、shadcn/ui Alert 提醒框
适合放：
- 注意事项
- 文章阅读提醒
- 使用前提
- 易错点
- 不适合放太长正文
写作提醒
不要用“很多人以为……”硬造反方。能直接说清楚的地方，就直接说清楚。
Alert 示例代码
<Alert>
<AlertTitle>写作提醒</AlertTitle>
<AlertDescription>
不要用“很多人以为……”硬造反方。能直接说清楚的地方，就直接说清楚。
</AlertDescription>
</Alert>八、shadcn/ui Card 卡片
适合放：
- 工具步骤
- 文章框架
- 来源卡概览
- 推荐阅读
- 后续选题
结构建议：问题是什么 → 做到什么算解决 → 最小动作 → 标准路径 → 常见错误。
结构建议：先破误解 → 给定义 → 拆机制 → 给判断标准 → 引出后续文章。
Card 示例代码
<div className="grid gap-4 md:grid-cols-2">
<Card>
<CardHeader>
<CardTitle>工具箱文章</CardTitle>
<CardDescription>适合解决一个明确问题。</CardDescription>
</CardHeader>
<CardContent>
结构建议：问题是什么 → 做到什么算解决 → 最小动作 → 标准路径 → 常见错误。
</CardContent>
</Card>
</div>九、shadcn/ui Button 按钮
适合放：
- 跳转链接
- 下载按钮
- 阅读下一篇
- 返回专题页
Button 示例代码
<div className="flex flex-wrap gap-3">
<Button>默认按钮</Button>
<Button variant="secondary">次级按钮</Button>
<Button variant="outline">边框按钮</Button>
<Button variant="ghost">幽灵按钮</Button>
</div>十、组合示例：来源卡展示
下面这个结构适合放在文章末尾。
十一、组合示例：后续选题展示
核心问题：听课时觉得很懂，一做题就不会。文章重点放在“看懂”和“能做”之间缺了什么。
核心问题：错题本记了很多，但下次还是错。文章重点放在“找错误判断”，而不是抄答案。
核心问题：时间花了很多，但进步不明显。文章重点放在“没有反馈的努力容易变成重复”。
核心问题：知道要练习，但不知道一次学习应该怎么安排。文章重点放在可执行模板。
十二、常用安装命令
Fumadocs 组件
npx @fumadocs/cli@latest add accordionnpx @fumadocs/cli@latest add tabsshadcn/ui 组件
pnpm dlx shadcn@latest add button card badge alert如果项目没有安装对应组件，MDX 会报找不到模块，例如：
Module not found: Can't resolve '@/components/ui/card'十三、MDX 避坑清单
十四、推荐使用规则
写正文
优先用：
- Markdown 标题
- 普通段落
- 加粗
- 列表
- 引用块
- 表格
写辅助内容
优先用：
- Fumadocs Accordion
- Fumadocs Tabs
- shadcn Alert
- shadcn Badge
- shadcn Card
少用
- 大段 JSX 嵌套
- shadcn Accordion 写长文档
- 为了样式过度包
<div> - 把整页内容包进代码块
十五、最小模板
以后新写一篇 MDX 文章，可以从这个模板开始：
---
title: 文章标题
description: 一句话说明这篇文章解决什么问题。
---
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
> 题记或一句核心判断。
---
## 一、问题是什么
这里写正文。
## 二、做到什么算解决
这里写判断标准。
## 三、现在最小能做什么
这里写最小动作。
---
## 依据和来源
<Accordions type="multiple">
<Accordion title="来源卡 01：标题" id="source-01">
**核心来源：** 来源名称。
**支撑观点：** 这条来源支撑什么观点。
**本文用法：** 这条来源用在文章哪里。
</Accordion>
</Accordions>