Biome Markdown 格式化器如何处理嵌入 CSS 的代码块:multiparser-css 测试规格深度解析
Biome Markdown 格式化器如何处理嵌入 CSS 的代码块:multiparser-css 测试规格深度解析
本文以 Biome 仓库中的一份 Prettier 兼容性测试规格 crates/biome_markdown_formatter/tests/specs/prettier/markdown/multiparser-css/css-comment.md 为线索,讲解 Biome Markdown 格式化器对围栏代码块(fenced code block)的保真输出策略、围栏长度归一化规则,以及这类规格文件是如何通过测试框架与 Prettier 输出进行对照验证的。读完本文,你将理解"Markdown 里嵌着 CSS/PostCSS 代码"这一场景在 Biome 中的实际格式化行为,并能自行运行、阅读此类快照测试。
规格文件定位:一份 Prettier 兼容性测试输入
该文件位于 Biome Markdown 格式化器的测试规格目录下:
- 路径:
crates/biome_markdown_formatter/tests/specs/prettier/markdown/multiparser-css/css-comment.md - 所属目录:
crates/biome_markdown_formatter/tests/specs/prettier/markdown/
从目录结构看,specs/prettier/markdown/** 专门存放用于与 Prettier 对比的兼容性用例。测试入口在 prettier_tests.rs:
tests_macros::gen_tests! {"tests/specs/prettier/markdown/**/*.{md}", crate::test_snapshot, ""}
gen_tests! 宏会把该目录下每一个 .md 文件展开为一个独立的测试函数;test_snapshot 函数随后以该文件为输入,构造 PrettierSnapshot 执行格式化并生成快照。因此,css-comment.md 本质上不是一篇说明文档,而是一份测试输入规格——它用一段真实的、带有复杂注释的 PostCSS 代码块,检验 Biome 在格式化"Markdown 中嵌入其他语言代码"这一多解析器(multiparser)场景下的行为。multiparser-css 这个目录名正是对这一场景的概括。
用例内容拆解:PostCSS 容器查询与注释
规格文件全文如下(pcss 语言围栏):
.Avatar {
/* ... */
&__image {
/* ... */
@container (width > 100px) {
/*
Change some styles on the image element when the container is
wider than 100px
*/
}
}
@container (aspect-ratio > 3) {
/* Change styles on the avatar itself, when the aspect-ratio is grater than 3 */
}
@container (width > 100px) and (height > 100px) {
/* ... */
}
}
这段用例刻意选择了对"重新排版"高度敏感的特性:
.pcss语言标识:明确告诉解析器这是 PostCSS,而非纯 CSS;- 嵌套选择器
&__image:PostCSS/Sass 风格的嵌套语法; - 多条
@container容器查询:包含width > 100px、aspect-ratio > 3、以及(width > 100px) and (height > 100px)组合条件; - 多种形态的注释:占位注释
/* ... */、跨越多行的块注释、以及单行内联注释。
这些元素共同构成一个"格式化器容易动手脚"的样本:如果格式化器对代码块内容做任何重排、缩进调整或注释归一化,这份用例的输出就会与 Prettier 不一致。它验证的核心行为是:Markdown 围栏代码块内的内容应被视作不透明文本原样保留。
格式化器如何保真输出:fenced_code_block 与 code_content 源码
Biome 的 Markdown 格式化器把围栏代码块拆成"围栏本身"与"块内容"两部分分别处理,对应两个源码文件。
围栏归一化:CommonMark §4.5 的最小围栏长度规则
FormatMdFencedCodeBlock 负责输出开/闭围栏。其关键逻辑在 fmt_fields 中(fenced_code_block.rs):
// Compute the minimum fence length needed (CommonMark §4.5).
// The fence must be strictly longer than any same-character sequence
// in the content, otherwise the inner sequence would be parsed as a
// closing fence. E.g. if the content contains ``` (3 backticks),
// the outer fence needs at least 4.
let max_inner = longest_fence_char_sequence(node, '`');
let fence_len = (max_inner + 1).max(3);
let normalized_fence: String = std::iter::repeat_n('`', fence_len).collect();
这条规则源自 CommonMark 规范 §4.5:围栏必须严格长于内容中出现的任意同字符连续序列,否则内层的反引号串会被误解析为闭合围栏。实现上,辅助函数 longest_fence_char_sequence 遍历代码块内容,统计 ` 的最长连续长度,最终围栏长度取 max_inner + 1 与 3 的较大值;随后开、闭围栏都会被替换为统一归一化后的反引号串(闭围栏同理,见 fenced_code_block.rs)。这意味着:围栏可以被改写,但内容必须原样保留。
内容保真:逐行按字面输出
FormatMdCodeContent 负责输出代码块正文。其核心行为是拿到 value_token 后,将文本按行切分并以字面换行符原样输出(code_content.rs):
- 跳过开围栏行尾的换行符与信息串附带的空白 trivia;
- 逐行剥离"开围栏缩进"对应的可选前导空格(
opening_fence_indent),其余字节不做任何改写; - 完整处理
\n、\r\n、\r三种换行形态,兼容不同平台的换行符。
换句话说,PostCSS 块内的嵌套缩进、多行注释的原始排版、容器查询的条件表达式,全部作为普通字节流透传。这也解释了为什么 css-comment.md 中的注释保持原样——格式化器根本不会解析 CSS 语法,也就无从"美化"注释。
为什么不调用内嵌语言格式化器
从源码结构看,crates/biome_markdown_formatter/src/lib.rs 的上下文结构中存在 _delegate_fmt_embedded_nodes: bool 字段(lib.rs),当前为 false。可以推断:Markdown 格式化器目前不会把代码块内容委托给内嵌语言的格式化器。虽然仓库中确实存在独立的 CSS 格式化器 crate(crates/biome_css_formatter),但它在 Markdown 文档格式化流程中并不参与对代码块内部的处理。因此,multiparser-css 目录虽然沿用了 Prettier 测试套件中"multiparser"的命名,实际验证的却是 Biome 的"不做二次解析、保持字面输出"策略。
测试如何驱动:从规格文件到快照对比
每个规格文件的执行链路在 prettier_tests.rs 中定义:
fn test_snapshot(input: &'static str, _: &str, _: &str, _: &str) {
countme::enable(true);
let root_path = Utf8Path::new(concat!(
env!("CARGO_MANIFEST_DIR"),
"/tests/specs/prettier/"
));
let test_file = PrettierTestFile::new(input, root_path);
let options = MdFormatOptions::default()
.with_indent_style(IndentStyle::Space)
.with_indent_width(IndentWidth::default());
let language = language::MarkdownTestFormatLanguage::gfm();
let snapshot = PrettierSnapshot::new(test_file, language, MdFormatLanguage::new(options));
snapshot.test()
}
要点如下:
- 输入定位:
PrettierTestFile::new(input, root_path)以tests/specs/prettier/为根,按相对路径加载css-comment.md; - 格式化选项:缩进风格为空格(
IndentStyle::Space),缩进宽度取默认值;Markdown 语言按 GFM(GitHub Flavored Markdown)解析; - 基准对照:
PrettierSnapshot负责将 Biome 的格式化输出与 Prettier 的基准输出进行快照对比,目录中的.prettier-snap文件即此类基准产物。若 Biome 对围栏代码块内容做了任何多余改写,快照对比就会暴露差异。
在本地运行该用例,可以使用(test 文件即 prettier_tests,生成的用例名按规格文件路径展开):
cargo test -p biome_markdown_formatter --test prettier_tests
测试通过意味着 Biome 对这段嵌入 PostCSS 的 Markdown 文档,其输出与 Prettier 完全一致。
从测试规格读出的设计意图
回到这份 css-comment.md,可以归纳出 Biome Markdown 格式化器在"内嵌代码"场景下的三条设计取舍:
- 代码块是黑盒:围栏内的任何语言(CSS、PostCSS、JS 等)都按字面文本保留,不解析、不重排、不规范化注释,保证 Markdown 文档中的代码片段绝对稳定;
- 围栏本身可归一化:按 CommonMark §4.5 计算最小围栏长度,统一开/闭围栏的反引号数量,保证文档即使在内容中出现反引号串时依然可被正确解析;
- 与 Prettier 行为对齐:通过
specs/prettier/markdown/**下的规格文件持续回归验证,任何与 Prettier 输出不一致的改动都会被快照测试拦截。
如果需要在真实项目中观察这一行为,只需在任意 Markdown 文件中编写带 pcss、css 或 scss 语言标识的围栏代码块并运行 Biome 的格式化命令,即可复现本用例的保真效果。相关源码、测试与规格文件的入口均已在上文给出,可进一步深入阅读。