Biome Markdown 格式化器行内图片Inline Image格式化规范与实现解析【免费下载链接】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导读行内图片是 Markdown 中最常用的语法之一格式看似简单却同时涉及 alt 文本、图片地址destination与可选标题title三个部分的规范化处理。本文以 Biome 仓库中的格式化规格测试 inline_image.md 及其快照 inline_image.md.snap 为骨架逐条拆解 Biome 对行内图片的全部 21 个格式化行为并结合格式化器源码inline_image.rs、inline_link.rs与语法树定义讲清输入什么、输出什么、为什么。读完本文你将能准确预测 Biome 对任意行内图片语法的格式化结果并理解这些规则在 AST 层面是如何落地的。一、这份文档是什么一个以测试用例为规格的规格文件inline_image.md不是传统意义上的说明文档而是 Biome Markdown 格式化器测试体系中一份以输入为规格、以快照为期望输出的测试输入文件。它的定位可以从测试基础设施看出测试入口 spec_tests.rs 通过宏tests_macros::gen_tests! {tests/specs/markdown/**/*.md, crate::spec_test::run, }将tests/specs/markdown/目录下每一个.md文件自动注册为一个规格测试每个输入文件对应的.snap快照由 snapshot_builder.rs 生成记录了Input原始输入与Formatted格式化结果两者对照即构成完整的规则说明书。因此阅读本规格的正确姿势是把 21 个输入用例当作问题集合把快照中的输出当作标准答案。下面先给出全部用例的输入原文与规格文件逐字一致再逐一对照快照输出讲解每条规则。规格输入全文21 个用例alt text alt text alt text alt text alt text alt text  alt text alt with spaces alt alt text alt   a  alt with **bold** and *italic* alt with code alt with code foo-bar) encodedfoo-%3Ebar)二、行内图片的语法结构与格式化入口在深入行为之前先建立语法层面的认知。Biome 的 Markdown 语法树把行内图片建模为MdInlineImage节点其字段定义位于 nodes.rspub struct MdInlineImageFields { pub excl_token: SyntaxResultSyntaxToken, // ! pub l_brack_token: SyntaxResultSyntaxToken, // [ pub alt: MdInlineItemList, // alt 文本行内元素列表 pub r_brack_token: SyntaxResultSyntaxToken, // ] pub l_paren_token: SyntaxResultSyntaxToken, // ( pub destination: MdInlineItemList, // 图片地址行内元素列表 pub title: OptionMdLinkTitle, // 可选标题 pub r_paren_token: SyntaxResultSyntaxToken, // ) }注意两个关键点alt 与 destination 都是MdInlineItemList行内元素列表而非普通字符串。这意味着 alt 文本内部可以嵌套行内强调**bold**、行内代码code等元素格式化时必须按行内元素而非纯文本来处理title 是可选的OptionMdLinkTitle这为空标题被删除的规则提供了类型层面的基础。对应的格式化实现是 inline_image.rs 中的FormatMdInlineImage其fmt_fields按照! [ alt ] ( destination [title] )的顺序逐段输出其中三个关键决策点分别是alt 文本以TextPrintMode::trim_all()模式打印keep_fences_in_italics: false允许在斜体场景下归一化围栏字符destination调用format_inline_destination(destination, TextPrintMode::Trim(TrimMode::AutoLinkLike))——图片地址使用AutoLinkLike风格的裁剪模式与普通链接inline_link.rs 中链接使用trim_all()存在细微差异title存在才打印不存在则跳过。三、逐条解析21 个用例的格式化行为与规则将快照Formatted段与输入逐条对照可以得到下表。这是本规格的核心成果也是本文最重要的参考表#输入格式化输出行为类别1alt textalt text常规形态原样保留2alt textalt text带标题原样保留3alt textalt text空双引号标题被移除4alt textalt text空单引号标题被移除5alt textalt text仅含空格的标题保留6alt textalt text单引号归一为双引号空格保留7空 alt 合法原样保留8alt textalt text标题内空格保留9alt with spacesalt with spacesalt 首尾空格保留10altaltdestination 首尾空白被裁剪11alt textalt textdestination 与标题间多余空格被压缩12altalt相对路径原样保留13绝对 URL 原样保留14URL 标题原样保留15aa单字符 alt destination 裁剪16长 alt 长 URL 长标题原样保留不强制换行允许超出 80 列17alt with **bold** and *italic*alt with **bold** and _italic_斜体*归一化为_18alt with \code|alt with code行内代码原样保留19alt with \code|alt with code多余的尖括号包裹被移除20foo-bar)encodedfoo-%3Ebar)括号 场景尖括号包裹 %3E编码21encodedfoo-%3Ebar)encodedfoo-%3Ebar)已编码形态保持幂等快照还额外记录了超出 80 字符最大宽度的告警段Lines exceeding max width of 80 characters其中仅用例 16 命中This is a long alt text ... And a long title too)。这说明行内图片属于不可分割的原子单元宁可超宽也不强行折行——这与链接/文本的可折行策略形成对比。下面按三个组成部分分组讲解这些行为背后的规则。3.1 规则一destination 的空白裁剪与AutolinkLike模式destination图片地址是格式化最积极的部分首尾空白一律裁剪 alt text alt with spaces alt alt text alt   a  alt with **bold** and *italic* alt with code alt with code foo-bar) encodedfoo-%3Ebar)二、行内图片的语法结构与格式化入口在深入行为之前先建立语法层面的认知。Biome 的 Markdown 语法树把行内图片建模为MdInlineImage节点其字段定义位于 nodes.rspub struct MdInlineImageFields { pub excl_token: SyntaxResultSyntaxToken, // ! pub l_brack_token: SyntaxResultSyntaxToken, // [ pub alt: MdInlineItemList, // alt 文本行内元素列表 pub r_brack_token: SyntaxResultSyntaxToken, // ] pub l_paren_token: SyntaxResultSyntaxToken, // ( pub destination: MdInlineItemList, // 图片地址行内元素列表 pub title: OptionMdLinkTitle, // 可选标题 pub r_paren_token: SyntaxResultSyntaxToken, // ) }注意两个关键点alt 与 destination 都是MdInlineItemList行内元素列表而非普通字符串。这意味着 alt 文本内部可以嵌套行内强调**bold**、行内代码code等元素格式化时必须按行内元素而非纯文本来处理title 是可选的OptionMdLinkTitle这为空标题被删除的规则提供了类型层面的基础。对应的格式化实现是 inline_image.rs 中的FormatMdInlineImage其fmt_fields按照! [ alt ] ( destination [title] )的顺序逐段输出其中三个关键决策点分别是alt 文本以TextPrintMode::trim_all()模式打印keep_fences_in_italics: false允许在斜体场景下归一化围栏字符destination调用format_inline_destination(destination, TextPrintMode::Trim(TrimMode::AutoLinkLike))——图片地址使用AutoLinkLike风格的裁剪模式与普通链接inline_link.rs 中链接使用trim_all()存在细微差异title存在才打印不存在则跳过。三、逐条解析21 个用例的格式化行为与规则将快照Formatted段与输入逐条对照可以得到下表。这是本规格的核心成果也是本文最重要的参考表#输入格式化输出行为类别1alt textalt text常规形态原样保留2alt textalt text带标题原样保留3alt textalt text空双引号标题被移除4alt textalt text空单引号标题被移除5alt textalt text仅含空格的标题保留6alt textalt text单引号归一为双引号空格保留7空 alt 合法原样保留8alt textalt text标题内空格保留9alt with spacesalt with spacesalt 首尾空格保留10altaltdestination 首尾空白被裁剪11alt textalt textdestination 与标题间多余空格被压缩12altalt相对路径原样保留13绝对 URL 原样保留14URL 标题原样保留15aa单字符 alt destination 裁剪16长 alt 长 URL 长标题原样保留不强制换行允许超出 80 列17alt with **bold** and *italic*alt with **bold** and _italic_斜体*归一化为_18alt with \code|alt with code行内代码原样保留19alt with \code|alt with code多余的尖括号包裹被移除20foo-bar)encodedfoo-%3Ebar)括号 场景尖括号包裹 %3E编码21encodedfoo-%3Ebar)encodedfoo-%3Ebar)已编码形态保持幂等快照还额外记录了超出 80 字符最大宽度的告警段Lines exceeding max width of 80 characters其中仅用例 16 命中This is a long alt text ... And a long title too)。这说明行内图片属于不可分割的原子单元宁可超宽也不强行折行——这与链接/文本的可折行策略形成对比。下面按三个组成部分分组讲解这些行为背后的规则。3.1 规则一destination 的空白裁剪与AutolinkLike模式destination图片地址是格式化最积极的部分首尾空白一律裁剪
