Biome Markdown 格式化器如何逐字节保留围栏代码块内容mdn-background-6 测试用例与源码解析【免费下载链接】biomeA toolchain for web projects, aimed to provide functionalities to maintain them. Biome offers formatter and linter, usable via CLI and LSP.项目地址: https://gitcode.com/gh_mirrors/bi/biome导读crates/biome_markdown_formatter/tests/specs/prettier/markdown/code/mdn-background-6.md是 Biome Markdown 格式化器 Prettier 一致性测试套件中的一个输入用例内容是一段来自 MDN 文档的 CSS 代码叠放式径向渐变背景。本文以该用例为核心讲解 Biome 的 Markdown 格式化器如何处理围栏代码块fenced code block为什么代码块内部的空行、缩进和原始字符会被逐字节保留而文档开头的空行会被规范化移除并结合格式化器源码fenced_code_block.rs、code_content.rs与测试基础设施prettier_tests.rs给出可验证的依据。读完本文你将理解 Biome Markdown 格式化对代码块的内容不动、围栏归一设计原则以及这套 Prettier 一致性测试的运行方式。一、这个测试用例是什么一份来自 MDN 的 CSS 代码块该文件位于 Biome Markdown 格式化器的 Prettier 一致性测试目录下与其配对存在的是同名.prettier-snap快照文件mdn-background-6.md.prettier-snap。从目录命名看mdn-background-1.md至mdn-background-9.md是一组取自 MDNMozilla Developer Network文档的background相关 CSS 示例同目录下还有mdn-filter-1.md、mdn-padding-1.md、mdn-transform.md等 MDN 命名用例用于验证格式化器对真实世界 Markdown 文档中代码块的输出稳定性。输入文件 mdn-background-6.md 的完整内容如下注意文件第一行是一个空行其后是 css 围栏围栏内有三个连续空行CSS 主体中第三个radial-gradient的缩进与其他两个不一致是刻意保留的不整齐写法css .stacked-radial { background: radial-gradient( circle at 50% 0, rgb(255 0 0 / 50%), rgb(255 0 0 / 0%) 70.71% ), radial-gradient( circle at 6.7% 75%, rgb(0 0 255 / 50%), rgb(0 0 255 / 0%) 70.71% ), radial-gradient( circle at 93.3% 75%, rgb(0 255 0 / 50%), rgb(0 255 0 / 0%) 70.71% ) beige; border-radius: 50%; } 这段 CSS 演示了经典的三色叠放径向渐变圆形头像背景技巧三个radial-gradient分别从顶部、左下、右下发出红、蓝、绿三色并以beige作为兜底色。对格式化器而言它真正关心的不是 CSS 语义而是这段代码块的书写形式围栏后存在 3 个空行、梯度参数缩进混乱第三个梯度的circle at 93.3% 75%多缩进了 4 个空格收尾的) beige;缩进与其他梯度不同。这些不整齐恰恰是测试要锁定的目标。二、它验证了什么行为内容逐字节保留前导空行被移除将输入文件与配对快照逐行对比可以得到 Biome 必须复现的 Prettier 行为。期望输出mdn-background-6.md.prettier-snap如下css .stacked-radial { background: radial-gradient( circle at 50% 0, rgb(255 0 0 / 50%), rgb(255 0 0 / 0%) 70.71% ), radial-gradient( circle at 6.7% 75%, rgb(0 0 255 / 50%), rgb(0 0 255 / 0%) 70.71% ), radial-gradient( circle at 93.3% 75%, rgb(0 255 0 / 50%), rgb(0 255 0 / 0%) 70.71% ) beige; border-radius: 50%; } 对比输入与期望输出可以提炼出三个精确的行为观察文档开头的空行被移除输入第一行是空行期望输出直接以 css 开头。这是文档级前导空白leading trivia的规范化处理不属于围栏内容本身。围栏内部的空行被完整保留css 之后的 3 个空行原样保留一处不少。这符合 Markdown 语义——围栏代码块内的空白是代码的一部分改动它会破坏被嵌入代码如 CSS、Python的含义。代码内容逐字节保留三个梯度的缩进差异8 空格 vs 4 空格、) beige;的收尾缩进、rgb(255 0 0 / 50%)这种现代 CSS 空格语法全部原样输出格式化器没有对围栏内的 CSS 做任何重排或重缩进。同样的规律在同目录的 mdn-background-2.md 中也能印证其输入在 css 前有 2 个空行期望输出 mdn-background-2.md.prettier-snap 同样先移除前导空行再把围栏内 3 个空行与参差不齐的linear-gradient缩进原样保留。两个用例互相印证说明这是稳定规则而非偶然。三、运行机制这套 Prettier 一致性测试如何工作该用例不是手工维护的普通快照而是由自动化宏批量接入测试的。在 prettier_tests.rs 中有一行核心声明tests_macros::gen_tests! {tests/specs/prettier/markdown/**/*.{md}, crate::test_snapshot, }gen_tests!宏会把tests/specs/prettier/markdown/下所有*.md文件递归匹配**各生成一个测试用例mdn-background-6.md因此自动成为测试输入。测试体同文件 L13-L29的流程是以PrettierTestFile::new(input, root_path)加载输入文件与同目录的.prettier-snap期望输出构造MdFormatOptions::default()并显式设置IndentStyle::Space与默认IndentWidthL22-L24通过MarkdownTestFormatLanguage::gfm()以 GFM 模式解析 Markdown见 language.rs内部调用parse_markdown_with_cache(..., MarkdownParserOptions::default().with_gfm(true))用MdFormatLanguage格式化后交给PrettierSnapshot::test()将 Biome 输出与 Prettier 记录的期望输出逐字节比对。也就是说.prettier-snap文件是 Prettier 的黄金输出golden outputBiome 的目标不是自己看着合理而是与 Prettier 在这些真实 MDN 用例上保持字节级一致。四、源码级原理格式化器内部如何实现内容不动、围栏归一围绕这个用例的行为可以在 Biome Markdown 格式化器源码中找到对应的实现路径。4.1 围栏本身的归一化CommonMark §4.5 与最长反引号序列围栏由 fenced_code_block.rs 中的FormatMdFencedCodeBlock处理。它首先计算围栏长度L27-L34// 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();longest_fence_char_sequenceL176-L205遍历代码块内容统计内容中连续反引号的最大长度。若内容里出现了 3 个连续反引号外层围栏就必须升到 4 个反引号否则内容中的会被 CommonMark 解析成围栏结束符。在本用例中CSS 内容不含反引号max_inner 0因此fence_len取最小值 3围栏维持 css 不变——这与快照中输出完全一致。此外格式化器还会把开、闭围栏统一替换为同一长度format_replaced保证成对出现。4.2 内容区逐行输出的FormatMdCodeContent围栏内容由 code_content.rs 中的FormatMdCodeContent负责。其核心思路是把代码块内容当作原文字面量逐行输出L19-L85值 token 以围栏开头的换行为起点随后按行切分每一行调用format_slice以literal_line_breaks()原样打印而不是走 Markdown 常规的缩进/换行排版逻辑。这正是围栏内 3 个空行原样保留、梯度缩进差异原样保留的机制来源。实现中还有两个值得注意的细节围栏缩进的按行裁剪FormatMdCodeContentOptions.opening_fence_indent记录了开围栏的缩进宽度输出每行时会先跳过不超过该宽度的前导空格L42-L50。在 mdn-background-6 中围栏位于第 0 列opening_fence_indent 0因此代码行一个空格都不会被裁剪circle at 93.3% 75%,的 8 空格缩进得以完整存活。跨平台换行处理L36-L40 与 L57-L81 对\r\n、\r、\n三种换行分别处理\r\n被归一为统一换行输出单独的\r则用literal_line_break_without_parent兜底保证 Windows 风格的 Markdown 也能稳定格式化。4.3 文档级前导空行不属于代码块的部分用例中输入首行空行被移除的行为发生在围栏之外——那是文档根级对前导空白leading trivia的规范化属于 Markdown 文档整体排版的一部分与代码块内容无关。从本用例与 mdn-background-2 的快照对比可以确认凡是围栏之外的前导空行都会被规整掉凡是围栏之内的空行都原样保留。这条边界正是格式化 Markdown 结构与绝不触碰嵌入代码两条原则的分水岭。五、同组用例对照代码块格式化的行为边界code/目录crates/biome_markdown_formatter/tests/specs/prettier/markdown/code下聚集了专门刻画代码块行为的用例族除本用例外还包括mdn-background-1.md~mdn-background-9.md、mdn-filter-*.md、mdn-padding-*.md、mdn-transform.md等 MDN 用例覆盖真实文档中各种语法高亮围栏css、js 等内代码的稳定性indent.md、leading-trailing-newlines.md分别考察围栏的缩进处理与围栏内首尾空行的保留。以 leading-trailing-newlines.md.prettier-snap 为例一个无语言标记的围栏内123 前后各 2 个空行在期望输出中均被完整保留backtick.md、format.md、lang.md、additional-space.md、ts-trailing-comma.md等覆盖内容含反引号、信息字符串info string、语言标签等边缘情形作为同目录输入文件存在均有对应.prettier-snap。把这些用例放在一起看Biome Markdown 格式化器对围栏代码块的行为边界非常清晰围栏的开闭标记与信息字符串属于 Markdown 语法可以被规范化围栏包裹的内容属于嵌入的另一种语言必须原样保留。FormatMdFencedCodeBlock中的has_quote_prefix、inside_list等分支fenced_code_block.rs进一步处理了代码块出现在列表、引用块中时的前缀对齐问题同样不触及代码内容本身。六、对使用者的实践启示代码块内容与格式化配置解耦Biome Markdown 的MdFormatOptions主要包含indent_style与line_width见 context.rs它们影响的是列表、段落、嵌套结构等 Markdown 排版而围栏代码块内容不参与这些规则。也就是说无论你把缩进风格设为空格还是 Tab、行宽设为多少mdn-background-6中的 CSS 输出都保持逐字节不变——这对在文档中内嵌对空白敏感的代码CSS 缩进、Python、YAML、shell 脚本至关重要。书写 Markdown 时的注意事项由于围栏内容被原样保留代码块内若出现与围栏同字符的连续序列如内容中有而外层也是 3 个反引号CommonMark 会提前结束代码块。格式化器会按 §4.5 自动把外层围栏加长来修复源码见 [fenced_code_block.rs](https://link.gitcode.com/i/858b4ddde48fb83ff0a7ac2224c9fea8#L27-L34)但最稳妥的做法仍是使用 4 个反引号包裹含的示例代码。如何复现与验证在本仓库中运行cargo test -p biome_markdown_formatter即可执行该 crate 的测试套件gen_tests!宏会依据tests/specs/prettier/markdown/**/*.{md}自动生成包括本用例在内的全部测试修改输入或期望输出文件后测试会立即暴露输出差异保证 Prettier 一致性不被破坏。结语mdn-background-6.md表面上只是一段 25 行的 CSS 示例但它承载了 Biome Markdown 格式化器一条重要的设计约定格式化器只负责 Markdown 语法层的规范化围栏长度、前导空行、信息字符串而把围栏内的内容视为不可侵犯的原文字面量逐行保留。这一约定在FormatMdCodeContent的逐行字面输出与FormatMdFencedCodeBlock的围栏归一化中落地并由prettier_tests.rs驱动的.prettier-snap黄金输出锁定为不可回退的测试契约。理解这一机制你就掌握了 Biome 处理Markdown 中嵌入代码这一高频场景的核心行为边界。【免费下载链接】biomeA toolchain for web projects, aimed to provide functionalities to maintain them. Biome offers formatter and linter, usable via CLI and LSP.项目地址: https://gitcode.com/gh_mirrors/bi/biome创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Biome Markdown 格式化器如何逐字节保留围栏代码块内容mdn-background-6 测试用例与源码解析【免费下载链接】biomeA toolchain for web projects, aimed to provide functionalities to maintain them. Biome offers formatter and linter, usable via CLI and LSP.项目地址: https://gitcode.com/gh_mirrors/bi/biome导读crates/biome_markdown_formatter/tests/specs/prettier/markdown/code/mdn-background-6.md是 Biome Markdown 格式化器 Prettier 一致性测试套件中的一个输入用例内容是一段来自 MDN 文档的 CSS 代码叠放式径向渐变背景。本文以该用例为核心讲解 Biome 的 Markdown 格式化器如何处理围栏代码块fenced code block为什么代码块内部的空行、缩进和原始字符会被逐字节保留而文档开头的空行会被规范化移除并结合格式化器源码fenced_code_block.rs、code_content.rs与测试基础设施prettier_tests.rs给出可验证的依据。读完本文你将理解 Biome Markdown 格式化对代码块的内容不动、围栏归一设计原则以及这套 Prettier 一致性测试的运行方式。一、这个测试用例是什么一份来自 MDN 的 CSS 代码块该文件位于 Biome Markdown 格式化器的 Prettier 一致性测试目录下与其配对存在的是同名.prettier-snap快照文件mdn-background-6.md.prettier-snap。从目录命名看mdn-background-1.md至mdn-background-9.md是一组取自 MDNMozilla Developer Network文档的background相关 CSS 示例同目录下还有mdn-filter-1.md、mdn-padding-1.md、mdn-transform.md等 MDN 命名用例用于验证格式化器对真实世界 Markdown 文档中代码块的输出稳定性。输入文件 mdn-background-6.md 的完整内容如下注意文件第一行是一个空行其后是 css 围栏围栏内有三个连续空行CSS 主体中第三个radial-gradient的缩进与其他两个不一致是刻意保留的不整齐写法css .stacked-radial { background: radial-gradient( circle at 50% 0, rgb(255 0 0 / 50%), rgb(255 0 0 / 0%) 70.71% ), radial-gradient( circle at 6.7% 75%, rgb(0 0 255 / 50%), rgb(0 0 255 / 0%) 70.71% ), radial-gradient( circle at 93.3% 75%, rgb(0 255 0 / 50%), rgb(0 255 0 / 0%) 70.71% ) beige; border-radius: 50%; } 这段 CSS 演示了经典的三色叠放径向渐变圆形头像背景技巧三个radial-gradient分别从顶部、左下、右下发出红、蓝、绿三色并以beige作为兜底色。对格式化器而言它真正关心的不是 CSS 语义而是这段代码块的书写形式围栏后存在 3 个空行、梯度参数缩进混乱第三个梯度的circle at 93.3% 75%多缩进了 4 个空格收尾的) beige;缩进与其他梯度不同。这些不整齐恰恰是测试要锁定的目标。二、它验证了什么行为内容逐字节保留前导空行被移除将输入文件与配对快照逐行对比可以得到 Biome 必须复现的 Prettier 行为。期望输出mdn-background-6.md.prettier-snap如下css .stacked-radial { background: radial-gradient( circle at 50% 0, rgb(255 0 0 / 50%), rgb(255 0 0 / 0%) 70.71% ), radial-gradient( circle at 6.7% 75%, rgb(0 0 255 / 50%), rgb(0 0 255 / 0%) 70.71% ), radial-gradient( circle at 93.3% 75%, rgb(0 255 0 / 50%), rgb(0 255 0 / 0%) 70.71% ) beige; border-radius: 50%; } 对比输入与期望输出可以提炼出三个精确的行为观察文档开头的空行被移除输入第一行是空行期望输出直接以 css 开头。这是文档级前导空白leading trivia的规范化处理不属于围栏内容本身。围栏内部的空行被完整保留css 之后的 3 个空行原样保留一处不少。这符合 Markdown 语义——围栏代码块内的空白是代码的一部分改动它会破坏被嵌入代码如 CSS、Python的含义。代码内容逐字节保留三个梯度的缩进差异8 空格 vs 4 空格、) beige;的收尾缩进、rgb(255 0 0 / 50%)这种现代 CSS 空格语法全部原样输出格式化器没有对围栏内的 CSS 做任何重排或重缩进。同样的规律在同目录的 mdn-background-2.md 中也能印证其输入在 css 前有 2 个空行期望输出 mdn-background-2.md.prettier-snap 同样先移除前导空行再把围栏内 3 个空行与参差不齐的linear-gradient缩进原样保留。两个用例互相印证说明这是稳定规则而非偶然。三、运行机制这套 Prettier 一致性测试如何工作该用例不是手工维护的普通快照而是由自动化宏批量接入测试的。在 prettier_tests.rs 中有一行核心声明tests_macros::gen_tests! {tests/specs/prettier/markdown/**/*.{md}, crate::test_snapshot, }gen_tests!宏会把tests/specs/prettier/markdown/下所有*.md文件递归匹配**各生成一个测试用例mdn-background-6.md因此自动成为测试输入。测试体同文件 L13-L29的流程是以PrettierTestFile::new(input, root_path)加载输入文件与同目录的.prettier-snap期望输出构造MdFormatOptions::default()并显式设置IndentStyle::Space与默认IndentWidthL22-L24通过MarkdownTestFormatLanguage::gfm()以 GFM 模式解析 Markdown见 language.rs内部调用parse_markdown_with_cache(..., MarkdownParserOptions::default().with_gfm(true))用MdFormatLanguage格式化后交给PrettierSnapshot::test()将 Biome 输出与 Prettier 记录的期望输出逐字节比对。也就是说.prettier-snap文件是 Prettier 的黄金输出golden outputBiome 的目标不是自己看着合理而是与 Prettier 在这些真实 MDN 用例上保持字节级一致。四、源码级原理格式化器内部如何实现内容不动、围栏归一围绕这个用例的行为可以在 Biome Markdown 格式化器源码中找到对应的实现路径。4.1 围栏本身的归一化CommonMark §4.5 与最长反引号序列围栏由 fenced_code_block.rs 中的FormatMdFencedCodeBlock处理。它首先计算围栏长度L27-L34// 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();longest_fence_char_sequenceL176-L205遍历代码块内容统计内容中连续反引号的最大长度。若内容里出现了 3 个连续反引号外层围栏就必须升到 4 个反引号否则内容中的会被 CommonMark 解析成围栏结束符。在本用例中CSS 内容不含反引号max_inner 0因此fence_len取最小值 3围栏维持 css 不变——这与快照中输出完全一致。此外格式化器还会把开、闭围栏统一替换为同一长度format_replaced保证成对出现。4.2 内容区逐行输出的FormatMdCodeContent围栏内容由 code_content.rs 中的FormatMdCodeContent负责。其核心思路是把代码块内容当作原文字面量逐行输出L19-L85值 token 以围栏开头的换行为起点随后按行切分每一行调用format_slice以literal_line_breaks()原样打印而不是走 Markdown 常规的缩进/换行排版逻辑。这正是围栏内 3 个空行原样保留、梯度缩进差异原样保留的机制来源。实现中还有两个值得注意的细节围栏缩进的按行裁剪FormatMdCodeContentOptions.opening_fence_indent记录了开围栏的缩进宽度输出每行时会先跳过不超过该宽度的前导空格L42-L50。在 mdn-background-6 中围栏位于第 0 列opening_fence_indent 0因此代码行一个空格都不会被裁剪circle at 93.3% 75%,的 8 空格缩进得以完整存活。跨平台换行处理L36-L40 与 L57-L81 对\r\n、\r、\n三种换行分别处理\r\n被归一为统一换行输出单独的\r则用literal_line_break_without_parent兜底保证 Windows 风格的 Markdown 也能稳定格式化。4.3 文档级前导空行不属于代码块的部分用例中输入首行空行被移除的行为发生在围栏之外——那是文档根级对前导空白leading trivia的规范化属于 Markdown 文档整体排版的一部分与代码块内容无关。从本用例与 mdn-background-2 的快照对比可以确认凡是围栏之外的前导空行都会被规整掉凡是围栏之内的空行都原样保留。这条边界正是格式化 Markdown 结构与绝不触碰嵌入代码两条原则的分水岭。五、同组用例对照代码块格式化的行为边界code/目录crates/biome_markdown_formatter/tests/specs/prettier/markdown/code下聚集了专门刻画代码块行为的用例族除本用例外还包括mdn-background-1.md~mdn-background-9.md、mdn-filter-*.md、mdn-padding-*.md、mdn-transform.md等 MDN 用例覆盖真实文档中各种语法高亮围栏css、js 等内代码的稳定性indent.md、leading-trailing-newlines.md分别考察围栏的缩进处理与围栏内首尾空行的保留。以 leading-trailing-newlines.md.prettier-snap 为例一个无语言标记的围栏内123 前后各 2 个空行在期望输出中均被完整保留backtick.md、format.md、lang.md、additional-space.md、ts-trailing-comma.md等覆盖内容含反引号、信息字符串info string、语言标签等边缘情形作为同目录输入文件存在均有对应.prettier-snap。把这些用例放在一起看Biome Markdown 格式化器对围栏代码块的行为边界非常清晰围栏的开闭标记与信息字符串属于 Markdown 语法可以被规范化围栏包裹的内容属于嵌入的另一种语言必须原样保留。FormatMdFencedCodeBlock中的has_quote_prefix、inside_list等分支fenced_code_block.rs进一步处理了代码块出现在列表、引用块中时的前缀对齐问题同样不触及代码内容本身。六、对使用者的实践启示代码块内容与格式化配置解耦Biome Markdown 的MdFormatOptions主要包含indent_style与line_width见 context.rs它们影响的是列表、段落、嵌套结构等 Markdown 排版而围栏代码块内容不参与这些规则。也就是说无论你把缩进风格设为空格还是 Tab、行宽设为多少mdn-background-6中的 CSS 输出都保持逐字节不变——这对在文档中内嵌对空白敏感的代码CSS 缩进、Python、YAML、shell 脚本至关重要。书写 Markdown 时的注意事项由于围栏内容被原样保留代码块内若出现与围栏同字符的连续序列如内容中有而外层也是 3 个反引号CommonMark 会提前结束代码块。格式化器会按 §4.5 自动把外层围栏加长来修复源码见 [fenced_code_block.rs](https://link.gitcode.com/i/858b4ddde48fb83ff0a7ac2224c9fea8#L27-L34)但最稳妥的做法仍是使用 4 个反引号包裹含的示例代码。如何复现与验证在本仓库中运行cargo test -p biome_markdown_formatter即可执行该 crate 的测试套件gen_tests!宏会依据tests/specs/prettier/markdown/**/*.{md}自动生成包括本用例在内的全部测试修改输入或期望输出文件后测试会立即暴露输出差异保证 Prettier 一致性不被破坏。结语mdn-background-6.md表面上只是一段 25 行的 CSS 示例但它承载了 Biome Markdown 格式化器一条重要的设计约定格式化器只负责 Markdown 语法层的规范化围栏长度、前导空行、信息字符串而把围栏内的内容视为不可侵犯的原文字面量逐行保留。这一约定在FormatMdCodeContent的逐行字面输出与FormatMdFencedCodeBlock的围栏归一化中落地并由prettier_tests.rs驱动的.prettier-snap黄金输出锁定为不可回退的测试契约。理解这一机制你就掌握了 Biome 处理Markdown 中嵌入代码这一高频场景的核心行为边界。【免费下载链接】biomeA toolchain for web projects, aimed to provide functionalities to maintain them. Biome offers formatter and linter, usable via CLI and LSP.项目地址: https://gitcode.com/gh_mirrors/bi/biome创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
