企业官网建设流程全解析

• 开发工具
• Lint
• 格式化
• 静态分析
• 代码质量
• 前端

本文以 Biome 仓库中的格式化工件 blockquote.md 及其配套快照（.snap）为核心依据，系统梳理 Biome Markdown 格式化器对引用块（blockquote）的规范化行为：包括标记符空格规范化、嵌套层级展开、懒续行合并、边界空行修剪、超长行检测，以及引用块与代码块、列表的组合格式化规则。读完本文，你将能准确预测任意 Markdown 引用块经 Biome 格式化后的输出，并能复现与验证这些规则。

一、blockquote.md：一份可执行的格式化规范

在 Biome 仓库中，blockquote.md 是 Markdown 格式化器（biome_markdown_formatter）的测试规范文件（spec）。这类文件与大多数"文档"不同：它不是给人阅读的散文，而是一份可直接编译执行的输入样例——测试框架会读取该文件内容作为输入，运行格式化器，再将输出与同目录下的 blockquote.md.snap 快照进行比对，任何不一致都会导致测试失败。

快照文件头部记录了生成方式：

source: crates/biome_formatter_test/src/snapshot_builder.rs info: markdown/blockquote.md

即快照由 snapshot_builder.rs 生成，info字段标明其对应的源 spec 文件。因此，这份文档 + 快照的组合，就是引用块格式化规则的"白纸黑字"规范，下面所有结论均可在输入/输出对中逐条验证。

二、标记符规范化：空格的处理边界

Markdown 的引用标记是>（及可选的后续空格）。Biome 格式化器对标记后的空格有一套明确的处理策略，从 blockquote.md 的前四组用例即可看出：

三条结论值得强调：

1. 缺空格补齐：>no space会被规范化为> no space，这是引用块最基本的可读性修复；
2. 多空格保留：> extra space的两个空格不会被折叠。这一点在源码中也有印证——引用内容的缩进语义（如 4 空格缩进的代码块）依赖标记后的空格数量，因此格式化器不会粗暴截断；
3. 不主动断行：即使是超长的一行引用内容，格式化器也不会将其拆分为多行，而是保持原样（同时会在诊断中报告超宽，详见第六节）。

三、嵌套引用的展开：>>到> >

引用块支持任意层级嵌套。Biome 的规范化策略是把紧凑写法的多级标记展开为逐级带空格的写法：

规则总结为：每级引用标记之间补一个空格，因此：

• 两级>>→> >
• 三级>>>→> > >
• 已经写成> >形式的不再改动（保持幂等，格式化两次结果一致）

这一规范化让嵌套层级在视觉上一目了然，也保证了后续讨论的"懒续行合并"（见第五节）能在统一的标记形态上进行。

四、引用块内的行内内容与段落结构

引用块内部可以是完整的 Markdown 内容，Biome 对行内元素与段落结构均有处理：

4.1 行内格式规范化

> quote with **bold** and *italic* → > quote with **bold** and _italic_

注意*italic*被规范化为_italic_（斜体标记符统一为下划线），而**bold**保持不变。这是 Biome Markdown 格式化器通用的行内标记规范化，在引用块内部同样生效。此外：

> quote with `inline code` → 不变 > quote with [a link](https://example.com) → 不变

行内代码与链接原样保留，不做改动。

4.2 多段落与空行

> first paragraph > > second paragraph

输出保持原样：段落间的空行由独立的>标记行构成，不会被折叠或移除。与此相对，真正会被修剪的是"边界空行"（见第六节）。

4.3 缩进内容保留

> indented content → > indented content

标记后的 4 空格缩进被原样保留。这是引用块内缩进代码（indented code）的语义基础，格式化器不能破坏它。

4.4 多个空行与短内容

> line one > > > line after multiple blanks

输出中连续的两个空引用行也保持不变。另外> short/> a]/> another short这类短内容、包含括号的异常内容均不做特殊处理，忠实保留。

五、懒续行（Lazy Continuation）：未标记行自动并入引用

Markdown 规范允许"懒续行"：引用块之后的缩进或不缩进的行，在渲染时仍属于引用内容。Biome 格式化器对此采取显式化策略——给续行补上引用标记，这一行为在输入/输出对中非常直观：

> quote continuation line → > quote continuation > line > > quote continuation line → > > quote continuation > > line

即：原本裸写的续行line，格式化后统一变成带完整层级标记的> line（二级嵌套则补> >）。相关专项用例见 blockquote_lazy_continuation.md：

## Canonical > foo - bar → 不变（规范写法） ## Unformatted > foo - bar → > foo - bar

这里更极端：- bar这种列表形式的懒续行，会被直接合并进引用内的同一行，变成> foo - bar。这说明懒续行合并不只是"补标记"，还可能把续行内容并到前一行末尾。对应的快照 blockquote_lazy_continuation.md.snap 证实了这一点。

值得注意的是，若续行已经写了完整标记（> quote continuation/> line），输出保持不变——只有"裸续行"才会被修复。

六、边界空行修剪与超长行检测

6.1 引用边界的空行修剪

看这段输入：

> > trimmed quote boundaries >

输入中引用块首尾各有一个孤立的空引用行，格式化后输出为：

> trimmed quote boundaries

首尾的空>行被完全移除，只保留实际内容行。这就是快照输出中"trimmed quote boundaries"用例的含义——引用块的边界空行属于冗余，Biome 会裁剪它们。

这项修剪逻辑在源码中有着落点：block_list.rs 中定义了QuoteBoundaryTrim枚举与配套的区间计算函数：

// crates/biome_markdown_formatter/src/markdown/lists/block_list.rs#L133-L174 pub(crate) enum QuoteBoundaryTrim { None, // 保留边界空行 Leading, // 仅移除内容前的引用空行 LeadingAndTrailing, // 移除内容前、后的引用空行 } pub(crate) fn quote_boundary_trim_range( node: &MdBlockList, quote_boundary_trim: QuoteBoundaryTrim, ) -> std::ops::Range<usize> { ... }

从源码注释（block_list.rs）可以进一步了解到实现细节：

• 起始修剪（quote_boundary_trim_start）：引用块开头可能存在两种"纯引用空行"形态——第一种由MdQuote节点自身前缀加一个前导MdNewline表示；后续的空行则以MdQuotePrefix + MdNewline成对出现。扫描会只修剪这两种精确形态，一旦遇到"引用前缀后紧跟真实内容"就立即停止；
• 结束修剪（quote_boundary_trim_end）：从后向前扫描，只移除末尾孤立的MdQuotePrefix（或MdQuotePrefix + MdNewline）形态；单独的MdNewline不足以判定为边界空行，必须其前一个块是MdQuotePrefix才行。

这两个函数体现了引用边界修剪的两个原则：只修剪"空行"，绝不误伤真实内容；CST 结构不同，修剪策略也要分形态处理。

6.2 超长行检测（80 字符）

快照文件末尾专门有一段"Lines exceeding max width of 80 characters"诊断：

48: > This is a long long long long long long long long long long long long long long long paragraph in a quote.

这表明 Biome Markdown 格式化器的默认行宽上限为80 字符（与lineWidth默认值一致）。当引用内容超过该宽度时，格式化器不会强行折行（保持引用原文不动），但会在诊断信息中报告超宽行及其行号（此处为输入的第 48 行）。这也解释了为什么第二节中"长行内容不截断"——超宽只是提示，不是改写。

七、引用块与代码块、列表的组合

除了 blockquote.md，同目录下还有一组姊妹 spec，覆盖引用块与其他块级元素的组合：

7.1 引用内的代码块：blockquote_code_block.md

> paragraph text > > ``` > code > ``` > paragraph text > > ```js > const x = 1; > ```

引用块内的围栏代码块（fenced code block，可带语言标识如js）每一行都带引用标记，格式化后保持该结构不变。引用内"段落 + 空引用行 + 代码块"的混合结构也原样保留。

7.2 引用内的列表：blockquote_list_items.md

> 1. first item > 2. second item > 3. third item > - alpha > - beta

引用内的有序列表与无序列表均保持原有编号与符号，不做重排。快照 blockquote_list_items.md.snap 确认输入输出完全一致。

7.3 列表内嵌引用：blockquote_list_stability.md

> - list > - nested > > quote > > continuation

列表项内再嵌引用块的"三明治"结构也被稳定保留，说明引用块的标记规范化不会破坏列表的缩进层级。

八、规则速查表与验证方法

8.1 引用块格式化规则速查

8.2 如何在本仓库复现验证

spec 测试由biome_markdown_formattercrate 的测试框架驱动。可在仓库根目录运行 Markdown 格式化器相关测试来复现上述所有行为（cargo test相关 target 以biome_markdown_formatter为前缀），或直接查看各.snap快照比对输入输出。若后续修改了格式化逻辑，只需重新生成快照并人工审查 diff，即可确认是否破坏上述规则。

九、总结

通过 blockquote.md 及其快照，Biome 的引用块格式化策略可以凝练为一句话：内容语义零改写，标记形态规范化。格式化器只负责修复"写法问题"——补空格、展开嵌套标记、合并懒续行、修剪边界空行、统一斜体标记——而绝不触碰内容本身：不折叠多空格、不拆分长行、不重排列表编号、不破坏缩进。这种"格式修复、内容不动"的设计原则，配合 block_list.rs 中按 CST 形态精确修剪边界的实现，保证了引用块格式化既安全可预测，又幂等稳定。

• 开发工具
• Lint
• 格式化
• 静态分析
• 代码质量
• 前端