Biome Markdown 格式化器如何处理嵌入 CSS 的代码块:multiparser-css 测试规格深度解析

原创2026-09-21 10:03:491,404 阅读
文章标签:开发工具Lint格式化静态分析代码质量前端

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 格式化器在"内嵌代码"场景下的三条设计取舍:

  1. 代码块是黑盒:围栏内的任何语言(CSS、PostCSS、JS 等)都按字面文本保留,不解析、不重排、不规范化注释,保证 Markdown 文档中的代码片段绝对稳定;
  2. 围栏本身可归一化:按 CommonMark §4.5 计算最小围栏长度,统一开/闭围栏的反引号数量,保证文档即使在内容中出现反引号串时依然可被正确解析;
  3. 与 Prettier 行为对齐:通过 specs/prettier/markdown/** 下的规格文件持续回归验证,任何与 Prettier 输出不一致的改动都会被快照测试拦截。

如果需要在真实项目中观察这一行为,只需在任意 Markdown 文件中编写带 pcss、css 或 scss 语言标识的围栏代码块并运行 Biome 的格式化命令,即可复现本用例的保真效果。相关源码、测试与规格文件的入口均已在上文给出,可进一步深入阅读。

登录后查看全文
biome