MDX 写作检查清单

MDX 的自由度越高，越需要写作纪律兜底。

MDX 很方便，也很容易被写成一锅粥。我的做法是先把文章当成一个小产品：标题负责导航，段落负责解释，列表负责拆步骤，代码块负责给证据，Callout 只用来提醒真正容易踩坑的地方。

写作检查清单 的目标不是把内容写得像规范文档，而是让每篇文章都能稳定通过构建、稳定被阅读、稳定出现在目录里。

先定文章骨架

我会先写三个层级：开头说明问题，## 拆大段，### 处理局部判断。不要一上来就堆段落，读者没有路标，很快就会迷路。

一篇普通技术笔记至少要有这些结构：

• 一个能说明主题的标题。
• 两到三个 ## 主段落。
• 必要时用 ### 拆出步骤或判断标准。
• 一个能复制的小代码块。
• 一个外部参考链接，例如 MDX 官方文档。

标题不是装饰

标题会进入目录，也会变成锚点。写标题时要避免“这里”“继续”“注意”这种含糊词，最好让它单独出现也能说明上下文。

1. 先写清楚问题。
2. 再补实现方式。
3. 最后写验证结果。

写代码块要给上下文

代码块最怕孤零零贴在那里。正文里先说明为什么需要这段命令，再放代码，后面补一句预期结果。

bun run lint
bunx tsc --noEmit
bun run build

这些命令不是仪式感。lint 看格式和静态规则，tsc 看类型边界，build 看 MDX 内容和路由能不能真的被编译。

内联代码也要克制，例如 updatedAt、slug、Callout 这种字段名适合用内联代码，普通中文句子就别乱包。

发布前做一次内容验收

最后我会把文章当成页面检查一遍，重点不是看自己写得多漂亮，而是看它有没有把页面弄乱。

• 桌面端目录能识别 h2 和 h3。
• 移动端没有横向滚动。
• 外链能打开新标签。
• 代码块可滚动，但页面本身不溢出。
• 三类提示块语义明确，没有滥用。

保持写作边界

MDX 能写组件，不代表每篇文章都该写组件。内容层的第一职责是表达，组件层的第一职责是渲染。把这两个边界守住，文章系统就不会越修越乱。

写作收尾表

• 用 Tab 检查链接焦点。
• 保留一处 真正有用 的表格。
• 发布前确认图片 alt 不是空话。