第 7 章 Markdown 与 MDX：文档语言

先说一个你可能没意识到的事实：这门语言你已经会了。这套书的五个文件全是 Markdown 写的，你读了三册，等于泡在语料里几星期。语法十分钟能列完：# 的个数是标题层级，**包住** 是粗体，- 起头是列表，[文字](网址) 是链接，三个反引号围出代码块，| 画表格，--- 是分隔线。就这些。

一门这么简单的语言，为什么统治了 README、CLAUDE.md、AI 的回答和我们这套书？三个理由。它是纯文本——所以 Git 能对它做红绿差异，文档从此和代码享受同等待遇：一样存档、一样 PR、一样审查（第二册的整套流程对文档同样生效）。它不渲染也能读——就算没有任何工具，打开就是干净的文字。它到处通用——GitHub、编辑器、AI 对话框，走哪都认。"文档进 Git"是现代工程的默认姿势，Markdown 就是这个姿势的载体。

接着认识它的进化形态：MDX = Markdown + 可以嵌入 React 组件。在 .mdx 文件里，大部分内容还是普通 Markdown，但你可以写 <TryIt>...</TryIt> 这样的自定义标签，让文档里长出交互块。我们 docs 网站上的"关键领悟"卡片、悬停出释义的术语，将来大概率就是这么实现的：内容仍是 Markdown，特殊块是组件。认脸有个小窍门（也是 JSX 的通行规矩）：大写开头的标签是组件，小写开头的是普通 HTML。

最后认一个文档的"名片"：front matter——文件顶部两条 --- 夹着的一小段 YAML（上一章刚学，立刻用上）：标题、日期、标签。docs 框架靠它生成侧边栏、排序和页面信息。你以后拆书成站，每一章头上都会有这么一张名片。

认脸卡

后缀 .md / .mdx；# 开头的标题；.mdx 里偶尔冒出大写开头的标签。

关键领悟

Markdown 是你和 AI 的母语交汇点——你用它写需求、写 CLAUDE.md、写红线，AI 用它回答你。把 Markdown 写清楚，就是把给 AI 的输入写清楚。

试一试

把你最近征服的一个新词，亲手按格式补进第一册附录 A（粗体术语加一句解释），commit，写清存档说明。这是你第一次以作者身份修改这套书——从此它真的是"活的"了。