Prettier 如何格式化 Markdown 中的 CSS 代码块以 MDN plaid-gradient 多背景渐变用例为例【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier本文基于 Prettier 仓库中的测试夹具tests/format/markdown/code/mdn-background-8.md完整剖析 Prettier 对 Markdown 内嵌 CSS 代码围栏code fence的双重打印机制外层由 Markdown 打印器管理围栏与缩进内层把代码块内容交给 CSS 打印器按 80 列宽度重新排版最终嵌回 Markdown 文档。读完本文你将掌握 Prettier 处理 Markdown 中代码块的完整链路、相关配置与测试验证方法并能在自己的 Markdown 文档中放心嵌入任意未格式化的 CSS 示例。一、用例背景一份乱缩进的 CSS 代码块tests/format/markdown/code/mdn-background-8.md是 Prettier 格式测试体系中的一份夹具fixture文件全文仅有一个css围栏内部是 MDN Web Docs 中经典的.plaid-gradient苏格兰格纹多背景渐变示例。从同目录下mdn-background-1.md到mdn-background-9.md、mdn-filter-1.md、mdn-font-face-1.md、mdn-mask-image.md、mdn-padding-1.md等一组夹具的命名与内容可以推断它们均取材于 MDN 文档中background等 CSS 属性页面用于覆盖各种真实世界中的 CSS 写法。夹具中的原始输入刻意塞入了大量不规则缩进与硬折行是检验格式化器鲁棒性的典型样例.plaid-gradient { background: repeating-linear-gradient( 90deg, transparent, transparent 50px, rgb(255 127 0 / 25%) 50px, rgb(255 127 0 / 25%) 56px, transparent 56px, transparent 63px, rgb(255 127 0 / 25%) 63px, rgb(255 127 0 / 25%) 69px, transparent 69px, transparent 116px, rgb(255 206 0 / 25%) 116px, rgb(255 206 0 / 25%) 166px ), repeating-linear-gradient( 0deg, transparent, transparent 50px, ... ), repeating-linear-gradient(45deg, transparent, transparent 5px, rgb( 143 77 63 / 25% ) 5px, rgb(143 77 63 / 25%) 10px); ... }注意输入中的几类脏写法transparent 69px顶格没有缩进、transparent与50px之间出现多个连续空格、rgb(143 77 63 / 25%)被硬拆成跨行、多个repeating-linear-gradient(...)挤在同一行、声明的换行位置完全错乱。这些正是 Prettier 格式化器需要统一处理的真实输入形态。二、测试如何驱动runFormatTest 与快照断言该夹具由同目录下的 format.test.js 驱动全部代码只有一行runFormatTest(import.meta, [markdown], { proseWrap: always });import.meta表明测试以当前目录下的全部夹具为输入目录中每个.md文件都会作为独立用例执行[markdown]指定使用 markdown 解析器{ proseWrap: always }设置散文换行策略为总是按 printWidth 换行保证测试在可复现的固定配置下进行默认printWidth为 80。runFormatTest定义于 tests/config/format-test/run-format-test.js它负责定位夹具目录、解析解析器、执行格式化并把结果与snapshots/format.test.js.snap 中的快照比对。快照中清晰地记录了该用例的 optionsparsers: [markdown]、proseWrap: always、printWidth: 80 (default)、完整输入与格式化输出三部分构成可回归验证的闭环。三、格式化结果逐段解析快照format.test.js.snap中mdn-background-8.md的输出第 669 行起展示了格式化后的规整结果核心变化如下.plaid-gradient { background: repeating-linear-gradient( 90deg, transparent, transparent 50px, rgb(255 127 0 / 25%) 50px, rgb(255 127 0 / 25%) 56px, transparent 56px, transparent 63px, rgb(255 127 0 / 25%) 63px, rgb(255 127 0 / 25%) 69px, transparent 69px, transparent 116px, rgb(255 206 0 / 25%) 116px, rgb(255 206 0 / 25%) 166px ), repeating-linear-gradient( 0deg, transparent, transparent 50px, rgb(255 127 0 / 25%) 50px, rgb(255 127 0 / 25%) 56px, transparent 56px, transparent 63px, rgb(255 127 0 / 25%) 63px, rgb(255 127 0 / 25%) 69px, transparent 69px, transparent 116px, rgb(255 206 0 / 25%) 116px, rgb(255 206 0 / 25%) 166px ), repeating-linear-gradient( -45deg, transparent, transparent 5px, rgb(143 77 63 / 25%) 5px, rgb(143 77 63 / 25%) 10px ), repeating-linear-gradient( 45deg, transparent, transparent 5px, rgb(143 77 63 / 25%) 5px, rgb(143 77 63 / 25%) 10px ); background: repeating-linear-gradient( 90deg, transparent 0 50px, rgb(255 127 0 / 25%) 50px 56px, transparent 56px 63px, rgb(255 127 0 / 25%) 63px 69px, transparent 69px 116px, rgb(255 206 0 / 25%) 116px 166px ), ... }逐条归纳格式化规则多背景分层换行background:后换行每个repeating-linear-gradient(...)层独占一行层间缩进 4 个空格输入中多个函数挤在同一行的写法被彻底展开。函数参数统一缩进每个渐变层内部参数每行缩进 6 个空格对齐逗号后统一为单个空格输入里顶格的transparent 69px、多空格分隔的transparent 50px全部被规整。被拆散的值重新合并输入中被硬折成三行的rgb(143 77 63 / 25%)被合并回单行同时现代空格分隔颜色语法rgb(255 127 0 / 25%)即rgb() 颜色值 alpha 斜杠写法原样保留不被改写。双值色标简写保持第二段背景中的双值色标简写transparent 0 50px、rgb(255 127 0 / 25%) 50px 56px保持原语义仅统一缩进。宽度自适应最后一个repeating-linear-gradient(45deg, ...)原本挤在一行因超过 80 列打印宽度而被展开为多行——说明代码块内的 CSS 同样遵守printWidth约束。四、底层原理Markdown 与 CSS 的双重打印链路4.1 代码块如何被让渡给 CSS 打印器Markdown 打印器在 src/language-markdown/print/mdast.js 中引入printCode定义于 src/language-markdown/print/code.js它区分两类代码节点缩进式代码块isIndented即 Markdown 中缩进 4 空格表示的代码保留原样仅统一为每行前 4 空格对齐不做语法级格式化围栏式代码块 包裹且有语言标识进入下一级处理。关键入口在 src/language-markdown/embed.js当code节点不是缩进式且有语言标识时Prettier 调用inferParser(options, { language })见 src/utilities/infer-parser.js根据围栏语言推断内部解析器——css语言对应 CSS 打印器js/ts/tsx等对应 JS 打印器其中ts与tsx还会通过覆盖filepath选项来区分泛型尾逗号规则。若无法推断解析器如未知语言则保持原样输出。本例css围栏被推断为 postcss 解析器进入 CSS 格式化流程。4.2 textToDoc把代码块内容当作独立文档格式化embed.js返回的异步函数通过textToDoc(node.value, { parser })将代码块内容交给对应语言的打印器重新排版这与 Prettier 的format核心流程复用同一套文档模型。因此Markdown 内嵌的 CSS 代码块享受与.css文件完全一致的格式化规则函数参数列表的逗号对齐、括号换行、颜色语法保持等行为均由 src/language-css/print/ 目录下的打印模块负责——从目录结构看comma-separated-value-group.js与sequence.js协作完成repeating-linear-gradient(...)这类逗号分隔值组的分行与缩进决策这解释了输出中层间 4 空格、参数 6 空格的对齐格局。4.3 围栏长度动态计算格式化完成后print/code.js 中的printCodeFences负责确定围栏符号的个数统计代码块内容中连续出现的的最大数量getMaxContinuousCount围栏长度取max(3, 连续数量 1)确保内容里即使出现反引号也不会破坏围栏该函数还以printWidth: Infinity将内部文档渲染为字符串用于计数而真正的 CSS 排版仍在外层 80 列约束下完成这就是上一节中超宽函数被展开的原因。最终输出由围栏 语言标识 换行 格式化后的内容 换行 围栏拼接而成并以markAsRoot标记为独立根文档。4.4 未格式化代码块的兜底如果代码块没有语言标识或属于缩进式代码块embed.js直接返回不触发内层格式化printCode退化为原样保留或仅做 4 空格对齐。这意味着 Prettier 不会冒险对无法识别语法的内容做语法级改写保证了 Markdown 中所有代码示例的语义安全。五、本用例的实战价值对 Markdown 文档作者写技术文档时完全无需手工整理示例代码的缩进Prettier 会统一处理且格式化是幂等的重复运行不会产生抖动。对 CSS 开发者多背景渐变repeating-linear-gradient叠多层的手工缩进最容易错乱此用例证明了 Prettier 能稳定还原这类复杂声明的结构现代颜色语法空格分隔 /alpha与双值色标简写均被安全保留。对测试读者mdn-background-8.md与其快照是一组活文档任何修改 CSS 打印逻辑的行为都会在此处被快照回归测试拦截是理解 CSS 打印器行为的绝佳切入点。六、如何在自己的环境中复现在当前仓库根目录下可以随时复现该用例# 直接对夹具文件运行 Prettier默认配置 printWidth 80 yarn prettier tests/format/markdown/code/mdn-background-8.md # 或运行该目录下的完整格式测试与快照比对 yarn jest tests/format/markdown/code更一般的用法是在任意.md文件中用css围栏包裹一段未格式化的 CSS然后对整篇文档运行yarn prettier --write README.md即可围栏内的 CSS 会自动获得与独立 CSS 文件一致的排版。七、小结tests/format/markdown/code/mdn-background-8.md虽只是一个测试夹具却浓缩了 Prettier 三大核心能力Markdown 打印器的节点分发printCode、跨语言嵌入格式化embedtextToDoc、以及动态围栏计算printCodeFences。它证明 Prettier 对 Markdown 内嵌代码的处理不是简单的原样保留而是真正理解代码内容并进行与源文件同等质量的格式化——这正是 Prettier 作为统一代码格式化器在文档场景下的关键价值。若要进一步探究可对比阅读同目录下mdn-background-1.md至mdn-background-9.md等系列夹具以及 src/language-css/print/ 与 src/language-markdown/print/code.js 的完整实现。【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考