从 special-prefix 测试用例看 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本文以 Biome 仓库中crates/biome_markdown_formatter的 Prettier 兼容性测试用例 special-prefix.md 为切入点剖析 Markdown 格式化器在面对「段落中出现-连字符」「README 式规则列表」「混合列表标记」「数字开头文本」等特殊前缀场景时的处理策略并结合 bullet_list.rs 与 paragraph.rs 源码解释列表标记统一、相邻列表分离与段落文本重排的底层原理。读完本文你将理解 Biome 的 Markdown 格式化器如何在保证「格式化后重新解析不回退语义」的前提下规范化列表与段落文本。一、用例定位Prettier 兼容性测试中的段落用例special-prefix.md位于 Biome Markdown 格式化器的 Prettier 兼容性测试目录crates/biome_markdown_formatter/tests/specs/prettier/markdown/paragraph/同目录下还有cjk.md、inline-nodes.md、lorem.md、simple.md、whitespace.md等用例共同覆盖段落paragraph节点的格式化行为。每个输入文件都配有一个同名.prettier-snap文件记录 Prettier 对该输入的格式化结果作为兼容性基准。这些用例由 prettier_tests.rs 中的宏统一驱动tests_macros::gen_tests! {tests/specs/prettier/markdown/**/*.{md}, crate::test_snapshot, }该宏遍历tests/specs/prettier/markdown/下所有.md文件并生成测试函数。每个测试通过PrettierTestFile读取输入与对应的.prettier-snap再用MdFormatOptions默认空格缩进、默认缩进宽度构造MdFormatLanguage最后交给PrettierSnapshot::test()对比 Biome 输出与 Prettier 基准输出。因此special-prefix.md本质上是验证「Biome 的 Markdown 段落与列表格式化结果是否与 Prettier 保持一致」的最小回归样例。二、用例逐段解读四种特殊前缀场景special-prefix.md全文由四个独立片段组成分别覆盖四种容易被 Markdown 语法误判的「特殊前缀」情形。1. 超长段落中的行内连字符abc abc abc abc abc abc abc abc abc abc abc abc abc abc abc abc abc abc abc abc - abc abc abc这是一行包含约 39 个abc的超长段落文本中间夹着一个孤立的-。该片段验证两个关键点段落内部的连字符-不应被误判为无序列表的起始标记列表标记必须位于行首超长段落不会被强制折行。对照 special-prefix.md.prettier-snap 可以看到格式化输出原样保留了这一整行说明段落文本重排遵循「保留源行结构、仅规范化内部空白」的策略而不是按宽度重新断行。同类证据也出现在 cjk.md.snap 中超长的中英文混合段落同样保持单行输出。2.-标记的 README 规则列表## Supported Rules - no-disabled-tests - disallow disabled tests. - no-focused-tests - disallow focused tests. - no-identical-title - disallow identical titles. - valid-expect - ensure expect is called correctly.这是典型的 README「规则清单」写法标题## Supported Rules后紧跟一个-标记的无序列表每项为「链接 破折号 描述」的单行结构。格式化后该列表保持原样——列表项内部的-只是行内文本不会触发重新分项列表标记统一为-。3.*标记与嵌套缩进的多行列表## Supported Rules * no-disabled-tests - disallow disabled tests. * no-focused-tests - disallow focused tests. * no-identical-title - disallow identical titles. * valid-expect - ensure expect is called correctly.这一片段使用*作为列表标记且每个列表项内部用「两空格缩进的-」续写描述文本构成列表项内的多行内容。从 prettier 快照输出可以看到格式化器保留了「标记 两空格缩进续行」的结构——列表项内的段落换行点被保留续行以两空格对齐到列表标记之后的位置。这里也验证了valid-expect项中「-位于行尾、描述换行」的写法同样被稳定保留。4. 数字开头的段落文本与有序列表误判She grew up in an isolated village in the 19th century and met her father aged 29. Oh no, why are we in a numbered list now?这一句以普通单词开头但中间出现aged 29. Oh——数字加句点紧邻大写单词是 Markdown 解析器识别有序列表项的最敏感形态29. Oh可被解读为列表标记。该用例确认只要数字序列不在行首、或后续内容不符合列表项结构解析器与格式化器都不会将其提升为有序列表整个片段仍作为普通段落输出。这也呼应了文件命名中 special-prefix 的含义——测试那些「看起来像列表前缀、实则不是」的边界情况。三、源码原理列表标记的统一与相邻列表分离special-prefix.md中同时出现了-与*两种无序列表标记。为什么格式化器允许它们在输出中共存答案在 bullet_list.rs 的标记规划逻辑中。ListMarkerPlan每个列表节点只决策一次ListMarkerPlan::from_listbullet_list.rs为每一个解析出的列表节点统一选择标记。源码注释明确指出标记必须按列表整体选择而非逐项选择——如果同一解析列表内既有-又有*格式化后的文本可能被 Markdown 重新解析成多个列表。ListBullet结构体bullet_list.rs中的unordered_marker字段即承载这一共享决策当列表计划选定*时源文件中的-、都会被替换为*。unordered_marker_for_list-/*/交替unordered_marker_for_list 实现了核心的交替策略偶数位sibling index 为 0、2、4…的列表默认使用-奇数位列表使用*若列表某一项以破折号构成的主题分隔符thematic break开头则偶数位改选避免输出- ---被解析为主题分隔符而非列表项。为什么必须交替源码注释给出了答案如果两个相邻的解析列表都用-打印重新解析时它们会被合并成一个松散列表loose list边界消失。交替标记能在格式化文本中保留列表边界。ordered_delimiter_for_list.与)交替有序列表同理ordered_delimiter_for_list 对偶数位列表使用.奇数位使用)。这样相邻的两个有序列表在重新解析时也不会被合并。Git diff-friendly 编号保留has_git_diff_friendly_ordered_list 负责识别「Git 友好编号」写法所有项都写1.渲染时自动递增。判定规则基于源标记数字序列1, 2, 3是顺序编号输出1, 2, 31, 1, 1是 Git 友好编号输出保持1, 1, 110, 1, 2保持10, 1, 1首个数字被保留为起始值0, 1视为顺序编号0, 1, 1视为 Git 友好编号。保留这种写法可以显著缩小 Git diff——在列表中间插入一项时无需重排后续所有行号。四、源码原理段落与列表项的格式化路径FormatMdParagraph 与段落选项段落节点由 FormatMdParagraph 格式化其Default实现使用TextPrintMode::fill()与TextContext::Neutral。FormatMdParagraphOptionsparagraph.rs暴露两个关键维度trim_mode是否裁剪段落起始空白通常由标题等父节点通过with_options传入text_context段落位于文档结构中的位置如是否处于列表项内供内联文本排版决策使用。在列表项内格式化段落时block_list.rs、quote.rs 等位置都会以FormatMdParagraphOptions覆写段落默认选项这正是special-prefix.md中列表项内多行文本能够被正确处理的原因。inline item list 的 fill 模式与文本规范化段落内部文本由 inline_item_list.rs 处理。该模块在print_mode.is_fill()时走fmt_fill分支inline_item_list.rs并在列表项上下文中结合TextContext::is_list()决定行首处理方式。TextPrintMode定义了fill、Trim、Remove等多种文本打印模式段落默认以 fill 模式用soft_line_break_or_space()inline_item_list.rs连接内联节点文本 token 则按上下文执行首尾裁剪与空白归一化——这解释了为什么格式化后行内多余空格被收敛而行结构得以保留。引用块前缀与列表项的续行对齐此外bullet_list.rs 的BulletListPrinter还处理列表项间的引用块前缀续行行首标记并借助list_marker_alignmentbullet_list.rs计算列表标记的对齐宽度保证special-prefix.md中「两空格缩进续行」这类多行列表项的视觉一致性。五、如何本地运行与验证该测试用例属于biome_markdown_formattercrate在仓库根目录执行cargo test -p biome_markdown_formatter即可运行包括 Prettier 兼容性快照在内的全部测试测试函数由gen_tests!宏按tests/specs/prettier/markdown/**/*.md路径自动生成。special-prefix.md对应的快照基准为同目录下的special-prefix.md.prettier-snap——若 Biome 输出与 Prettier 基准存在差异测试会像 cjk.md.snap 那样在快照的Prettier differences段中以 diff 形式呈现便于开发者逐项核对行为差异。六、小结special-prefix.md虽是一个不足 30 行的测试输入却浓缩了 Biome Markdown 格式化器在「段落与列表边界」上的完整设计考量行内连字符与数字不越界成列表、相邻列表通过-/*/与./)交替保持语义边界、Git diff-friendly 编号被识别保留、段落文本按 fill 模式规范化而保留源行结构。这些行为分别由 bullet_list.rs 的ListMarkerPlan与 paragraph.rs 的段落选项系统实现并被 prettier_tests.rs 的宏驱动的快照测试持续守护——这正是 Biome 格式化器在「格式化输出可再次被安全解析」这一核心目标上的具体体现。【免费下载链接】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），仅供参考