Biome useTopLevelHeading 规则深度解析:强制 Markdown 文档以一级标题开头
Biome useTopLevelHeading 规则深度解析:强制 Markdown 文档以一级标题开头
本文围绕 Biome 的 useTopLevelHeading 检查规则(对应 规则实现 与 测试用例)展开,剖析它的判定逻辑、边界情况和配置方法。读完本文,你将理解该规则如何在 README 与各类 Markdown 文档中强制"首块内容必须是一级标题",并掌握其例外场景(YAML front matter、HTML 块、主题分隔线、HTML 注释)背后的设计动机,能够直接在 biome.json 中启用它并准确解读 lint 诊断。
规则概述:Require Markdown documents to start with a top-level heading
useTopLevelHeading 是 Biome 针对 Markdown 语言提供的 lint 规则,声明位于 use_top_level_heading.rs,其核心行为是:
要求文档的第一个块(block)必须是 level-1 标题,可以是 ATX 形式(
# Heading),也可以是 setext 形式(Heading后跟===)。
该规则的关键元数据如下:
| 属性 | 值 |
|---|---|
| 规则名 | useTopLevelHeading |
| 版本 | 2.5.8 |
| 语言 | md(Markdown) |
| 是否推荐 | recommended: false,默认不启用,需显式开启 |
| 规则组 | nursery(尚未稳定,后续可能变化) |
| 来源 | markdownlint("md041", "first-line-heading") |
从源码可见,它明确借鉴了 markdownlint 的 md041(first-line-heading)规则(sources: &[RuleSource::MarkdownLint("md041", "first-line-heading").same()]),因此在语义上与 markdownlint 生态保持一致,方便迁移的用户对齐预期。
从测试用例说起:heading-2.md 验证了什么
关联文档 heading-2.md 是规则的 invalid 测试输入,全文只有两行:
<!-- should generate diagnostics -->
## Second level heading
它包含两个要点:
- 文档首块是一个
##二级标题——按照规则,首块必须是一级标题,因此应产生诊断; - 文件开头有一个 HTML 注释
<!-- should generate diagnostics -->——该注释在判定首块时会被忽略,不影响对##的检查。
对应的快照 heading-2.md.snap 记录了该用例的期望输出,诊断信息为:
heading-2.md:2:1 lint/nursery/useTopLevelHeading ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
i Missing top-level heading.
1 │ <!-- should generate diagnostics -->
> 2 │ ## Second level heading
│ ^^^^^^^^^^^^^^^^^^^^^^^
3 │
i The document should start with a top-level heading (h1) so readers and tools can identify its title.
Add a # Heading (or a level-1 setext heading) at the start of the document.
诊断范围精确指向 ## Second level heading 这一行(2:1),并附带了可操作的修复建议。这些快照由 spec_tests.rs 驱动,是规则行为回归测试的重要一环——任何改动导致行为与快照不一致,测试都会失败。
规则实现原理:源码级剖析
规则的完整判定逻辑集中在 use_top_level_heading.rs 的 run 方法中:
type Query = Ast<MdRoot>;
type State = TextRange;
type Signals = Option<Self::State>;
type Options = UseTopLevelHeadingOptions;
- Query 是
Ast<MdRoot>:规则以整篇文档的根节点为查询对象,因此是文档级(document-level)规则,而非块级规则; - State 是
TextRange:诊断定位到问题块的文本范围; - Options 是
UseTopLevelHeadingOptions:定义于 biome_rule_options/src/use_top_level_heading.rs,当前为一个空结构体,即该规则目前没有可配置的选项。
第一步:找到第一个"非可忽略"块
let first_block = root
.value()
.iter()
.find(|block| !is_ignorable_leading_block(block))?;
is_ignorable_leading_block(实现见此处)会跳过三类"前导噪音":
- HTML 注释块(
<!-- ... -->):无论作为MdHtmlBlock还是作为独立的MdParagraph,只要首 token 以<!--开头、末 token 以-->结尾即视为注释(见is_html_comment_block,L113-L131); - 纯换行块(
is_newline()); - 延续缩进块(
is_continuation_indent())。
这意味着文档开头可以放心保留 <!-- ... --> 这样的文件前导注释,不会误报。
第二步:对首块进行分类判定
run 方法对首块进行模式匹配,判定逻辑可以概括为下表:
| 首块类型 | 判定结果 |
|---|---|
ATX 标题(MdHeader)且 level() == 1 |
✅ 通过 |
ATX 标题且 level() != 1(如 ##) |
❌ 报告诊断 |
setext 标题(MdSetextHeader)且 is_level_1() |
✅ 通过 |
| setext 标题且非一级 | ❌ 报告诊断 |
主题分隔线(MdThematicBreakBlock) |
✅ 跳过(不报告) |
HTML 块(MdHtmlBlock,非注释) |
✅ 跳过(不报告) |
| 其他任何块(段落、列表、引用等) | ❌ 报告诊断 |
第三步:生成诊断
diagnostic 方法(L97-L110)生成的消息为 "Missing top-level heading.",并附带提示:
The document should start with a top-level heading (h1) so readers and tools can identify its title. Add a
# Heading(or a level-1 setext heading) at the start of the document.
完整测试矩阵:valid 与 invalid 用例
规则配套的测试目录 tests/specs/nursery/useTopLevelHeading/ 覆盖了多条正向与反向路径,是理解规则行为边界的最好教材。
invalid 用例(应产生诊断)
| 用例文件 | 输入要点 | 违规原因 |
|---|---|---|
| heading-2.md | <!-- comment --> + ## Second level heading |
首块是二级 ATX 标题 |
| setext-heading-2.md | 注释 + Second level heading + -------------------- |
首块是二级 setext 标题 |
| paragraph.md | 注释 + Some text + 后续才有 # Top-level heading |
首块是普通段落,标题出现位置不对 |
尤其值得注意 paragraph.md:即使文档后面出现了 # Top-level heading 一级标题,只要第一个块不是它,依然违规。这体现了规则对"位置"的严格要求——它检查的是"文档从一级标题开始",而不是"文档是否包含一级标题"。
valid 用例(不应产生诊断)
| 用例文件 | 输入要点 | 通过原因 |
|---|---|---|
| heading-1.md | 注释 + # Top-level heading |
首块为一级 ATX 标题 |
| setext-heading-1.md | 注释 + Top-level heading + ================= |
首块为一级 setext 标题 |
| html.md | <div>HTML content</div> + ## Second level heading |
首块为 HTML 块,被显式豁免 |
| yaml.md | YAML front matter(--- 包裹)+ ## Second level heading |
首块被解析为 YAML 块,不触发检查 |
例外与边界情况:为什么 HTML 块和 YAML front matter 被豁免
从源码注释(L15-L19)与上述 valid 用例可以提炼出四条明确的豁免规则:
- YAML front matter(yaml.md):以
---包裹的元数据块是 Jekyll、Hugo 等静态站点生成器的通用约定,文档正文的标题通常在 front matter 的title字段中声明,因此 front matter 不应被视为"正文首块"; - HTML 块(html.md):源码注释明确指出"有些项目会用 HTML 标记来书写标题,尤其是在 README 中"(
<h1>或<div>包裹的标题很常见),因此 HTML 块整体豁免; - 主题分隔线(thematic break,如
---):被归类为不报告的首块类型,避免把装饰性分隔线误判为"缺少标题"; - HTML 注释:仅作为文件前导说明文字存在,在判定时被完全忽略。
需要注意的是,豁免是有边界的:HTML 注释被忽略,但普通 HTML 块被豁免后,其后的二级标题不会报错;而普通段落、列表等"正文型"首块则严格报错。这种设计在"避免误伤 README 常见写法"与"维持文档标题可发现性"之间取得了平衡。
在项目中启用与配置
由于 recommended: false,useTopLevelHeading 不会随默认规则集启用,需要显式在 biome.json 中开启。在 linter.rules 下以规则组 nursery 进行配置:
{
"linter": {
"rules": {
"nursery": {
"useTopLevelHeading": "warn"
}
}
}
}
将级别设为 "error" 可让 CI 在文档缺少一级标题时直接失败;设为 "warn" 则仅提示不阻断。由于规则当前没有可配置选项(UseTopLevelHeadingOptions 为空结构体),无需也无法传入 options。
关于 nursery 组的说明
快照诊断末尾附带提示:
This rule belongs to the nursery group, which means it is not yet stable and may change in the future.
这意味着规则的行为、默认级别甚至名称都可能在后续版本调整。对于生产项目,建议先以 "warn" 观察一段时间的实际误报情况,再决定是否提升为 "error"。
同族规则与工程实践建议
在 crates/biome_markdown_analyze/src/lint/nursery/ 目录中还存在两条语义相邻的标题规则,共同构成 Biome 的 Markdown 标题检查体系:
useSingleTopLevelHeading(use_single_top_level_heading.rs):限制文档中一级标题的数量(通常只允许一个);useConsistentHeadingLevel(use_consistent_heading_level.rs):要求标题层级严格递增,不允许跳级。
实际工程中可以组合使用:useTopLevelHeading 保证"文档以 h1 开头",useSingleTopLevelHeading 保证"h1 只有一个",useConsistentHeadingLevel 保证"层级递进不跳级"。三者配合,即可对文档大纲结构形成完整的可维护性约束。
小结
useTopLevelHeading 是 Biome 面向 Markdown 文档结构的一项轻量而严格的约定式规则:它要求文档第一个有效块必须是一级标题(ATX 或 setext 均可),同时为 HTML 注释、HTML 块、主题分隔线与 YAML front matter 保留了合理的豁免空间。其判定逻辑简洁(一次遍历 + 模式匹配),诊断信息清晰可操作,并拥有覆盖正反两面的快照测试保障。对于以 README 为核心的仓库,启用该规则可以显著提升文档标题的可发现性与一致性,值得纳入团队的 Markdown lint 配置。