AI 生成的 MDX 模板大多一开始很漂亮，写到第 30 篇就难看了——一次性组件太多、间距不统一、版式跟内容打架。这篇给 10 个能扛到 1000+ 篇的版式模式，以及让 LLM 干净产出的 prompt 结构。
背景
MDX 是 Markdown 加组件，所以一个文章模板本质上就两个决定：哪些 Markdown 元素做全局样式，哪些专门组件对外暴露。AI 这两件都能做好，前提是你给它约束。让它”设计一个漂亮的文章模板”，出来就是渐变背景加 Tailwind 糊汤。给它一份固定组件清单加一篇内容样本，出来的东西真的能维护。下面 10 个模式是我们一个 1200 篇双语站正在用的。
模板漂移的成本是非线性的。50 篇时不一致还像”差一口气的修饰”。500 篇时每次漂移都要改几百个文件。1000+ 篇之后就停止 refactor 转而用样式覆盖绕过去——这是最差的中间状态。词汇表早定。
怎么判断你需要这个
- 在搭新内容站，或想刷一遍老站的版式。
- 当前模板每篇文章里有 6+ 个临时样式 div，自己都在反复调。
- 新作者（或 AI）每次都自创标题层级，因为模板没有清晰词汇表。
- 想用同一套模板撑教程、故障排查、清单、评测四类内容。
一句话结论
从下面 10 个里挑 5-7 个核心模式。每种定义成一个组件（或标准 HTML 元素上的 CSS 类）。禁止其他临时样式块。让 AI 在这个固定词汇表里生成文章，而不是每篇自创新形状。
10 个模式
- 步骤清单——带粗体起手短语的有序列表。用普通
<ol>加<strong>首句即可。不需要专门组件。 - 对比表——最多 3 列（选项、何时用、何时不用）。普通 Markdown 表格，全局加斑马纹和小写大写体头。
- 决策树——带条件缩进的列表。嵌套最多 2 层，更深就单独开一节。
- 结论盒——单段
<aside>，左侧边线样式。每篇文章靠前位置只放一个。 - 带说明的代码块——code block 紧跟一行斜体说明。不需要专门组件，用 CSS 兄弟选择器。
- 诊断表——症状 - 原因 - 修法，三列 Markdown 表格。故障排查类必用。
- 行内复选清单——
- [ ]任务列表。「开始前准备」一类章节常用。 - 引用块——真实的平台报错或拒绝原因截图文字。样式做成 callout，不是普通 blockquote。
- 对比示例——Bad / Good 代码或文本对。用
textcode block 加Bad:/Good:前缀就行，越简单越好。 - 相关链接组——
## 相关下的 3-6 条链接，总是在末尾，每篇形状一致。
让 LLM 出干净输出的 prompt 结构
给模型三样：固定模式清单、一篇真实 MDX 样本、新文章选题。用下面约束锚定 prompt：
- 只用列出的 10 个模式。不要发明新组件或样式 div。
- 标题：只用 ## 层级，内容确实超 4 个子节再用 ###。
- 不用 emoji，不用感叹号，不用营销腔。
- 首段：2-3 句，无标题。
- 末节始终是 "## 相关"，含 3-6 条链接。
- 语气和样本文一致。不挂样本文章，模型会在它训练数据上做平均，出来的就是通用 SaaS 博客腔。挂上样本，它会模仿你的风格——通常好到每篇 10 分钟微调就能用。
怎么强制执行词汇表
- 写一个 lint 脚本扫所有 MDX：数
##标题数、检查末节是不是## 相关、标记 allowlist 之外的组件、标记正文里的裸<div>标签。 - lint 挂到
prebuild。文件失败就 build 失败。这是 1000 篇文章保持齐整最便宜的办法。 - 新文章 PR 附一份小清单：用了 10 个模式里的哪几个，没用哪几个，为什么。
- 留一个
examples/目录，每个模式一份 MDX 当作活文档。AI 生成新内容时能读到。
老模板迁移
- 盘点现有所有文章里用到的组件。多数老模板有 30+ 个组件，一半只出现一次。
- 把每个现有组件映射到 10 个模式里的一个，或标记删除。目标 5:1 缩减。
- 跑一遍 codemod，把废弃组件替换成标准等价物。给 AI 3-5 个 before/after 例子，让它写 codemod 很容易。
- 50-100 篇一批迁。每批 build 一次；一篇意外炸了通常是 codemod 漏了某个边角情况。
容易踩的坑
- 让模型为「视觉多样性」自创新组件。多样性会杀掉一致性。模式清单本身就是多样性。
- 让模型「设计一个漂亮的模板」无约束。出来是渐变 + 动效 + 三种字体。
- 生成的组件没在 MDX 里实测。有些库会破坏 MDX 的花括号——先在一篇文章里跑通。
- 跳过样本文章。模型默认套用它训练集里流行的博客模板，不是你的风格。
- 每节之间加装饰性分隔线（
---）。MDX 渲染成<hr>，纯视觉噪声没信息量。
常见问答
- 能让模型直接设计组件吗？: 第一版可以。最终样式自己来或者跟设计师配模型。AI 提形状还行，挑间距和配色不行。
- 怎么防止 1000 篇里模板漂移？: 每个 MDX 文件 lint：标题层级对不对、末节是不是
## 相关、有没有用 allowlist 外的组件。30 行脚本能挡住 90% 的漂移。 - EN 和 ZH 能共用一套模板吗？: 能。间距、字体栈、行高定义一次。中文版通常需要更紧的行高和不同的字体回退；其他完全一致。
- 暗色模式怎么处理？: 定义语义色变量（background, foreground, muted, accent），组件全部用变量。绝不在组件里硬编颜色。
- 要不要用 shadcn 还是自己写？: 文章为主的内容站自己写。shadcn 适合应用 UI，文章站用它多余。200 行 CSS 加 5 个组件比挂一个组件库强。
- 代码高亮怎么处理？: 用构建期的 Shiki，不要浏览器期的 Prism。Shiki 不往客户端发任何 JS，渲染效果完全一样。配两套主题（明、暗），用 CSS 变量切换。
- 需要 MDX provider 注册全局组件吗？: 看实际复用度。
AsideCallout之类跨多文件用的组件再考虑。5 个组件的小词汇表，每文件 import 就行，build 更简单。 - MDX 里怎么处理响应式？: 响应式全放在 layout 层，MDX 里不要。文章正文就是 Markdown + 组件。外面的容器 layout 决定断点、流式字号、间距。
- 模板要不要做版本？: 非正式地做。大改动记到
CHANGELOG.md，知道哪些文章是在 v1 写的、哪些是在 v2 写的。排查老文章样式异常时帮助大。