Biome useTopLevelHeading 规则深度解析:强制 Markdown 文档以一级标题开头

原创2026-09-19 10:36:341,709 阅读
文章标签:开发工具Lint格式化静态分析代码质量前端

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

它包含两个要点:

  1. 文档首块是一个 ## 二级标题——按照规则,首块必须是一级标题,因此应产生诊断;
  2. 文件开头有一个 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 用例可以提炼出四条明确的豁免规则:

  1. YAML front matter(yaml.md):以 --- 包裹的元数据块是 Jekyll、Hugo 等静态站点生成器的通用约定,文档正文的标题通常在 front matter 的 title 字段中声明,因此 front matter 不应被视为"正文首块";
  2. HTML 块(html.md):源码注释明确指出"有些项目会用 HTML 标记来书写标题,尤其是在 README 中"(<h1> 或 <div> 包裹的标题很常见),因此 HTML 块整体豁免;
  3. 主题分隔线(thematic break,如 ---):被归类为不报告的首块类型,避免把装饰性分隔线误判为"缺少标题";
  4. 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 标题检查体系:

实际工程中可以组合使用:useTopLevelHeading 保证"文档以 h1 开头",useSingleTopLevelHeading 保证"h1 只有一个",useConsistentHeadingLevel 保证"层级递进不跳级"。三者配合,即可对文档大纲结构形成完整的可维护性约束。

小结

useTopLevelHeading 是 Biome 面向 Markdown 文档结构的一项轻量而严格的约定式规则:它要求文档第一个有效块必须是一级标题(ATX 或 setext 均可),同时为 HTML 注释、HTML 块、主题分隔线与 YAML front matter 保留了合理的豁免空间。其判定逻辑简洁(一次遍历 + 模式匹配),诊断信息清晰可操作,并拥有覆盖正反两面的快照测试保障。对于以 README 为核心的仓库,启用该规则可以显著提升文档标题的可发现性与一致性,值得纳入团队的 Markdown lint 配置。

登录后查看全文
biome