企业官网建设流程全解析

• 开发工具
• 代码质量
• Lint
• 静态分析

本篇指南聚焦 markdownlint 项目中MD041（first-line-heading/first-line-h1）规则与 YAML/TOML/JSON Front Matter 标题判定机制的完整链路，以仓库测试场景 front-matter-no-title-no-h1.md 为切入点，讲解"文档首行必须是顶级标题"这一约定在存在 Front Matter 时的判定逻辑、参数配置、修复方式与底层实现。读完你可以准确理解为什么"Front Matter 有内容但正文没有 H1"仍会触发MD041，并掌握allow_preamble、front_matter_title、level三个参数的实战用法。

场景文件：一个专门"制造违规"的测试用例

在 markdownlint 的测试目录中，test/front-matter-no-title-no-h1.md是一个精心构造的负面测试场景（violation case）。它的完整内容如下：

--- layout: post notitle: "Welcome to Jekyll!" date: 2015-11-17 16:16:01 -0600 categories: jekyll update --- Front matter from [Jekyll documentation](https://jekyllrb.com/docs/posts/#a-typical-post). {MD041} <!-- markdownlint-configure-file { "line-length": false } -->

这个文件的命名即点明了测试意图："front matter 存在，但没有 title 字段，正文也没有 H1 标题"（no-title-no-h1）。它复刻了 Jekyll 官方文档 中的典型博客文章头部，其中：

• Front Matter 声明了layout、notitle、date、categories等元数据；
• notitle字段故意不使用title这个标准命名，用于验证 MD041 规则默认不会把非title字段当作文档标题；
• 第 7 行正文文本行尾的{MD041}是测试标记（test marker），用于场景测试框架断言该行应命中MD041规则；
• 末尾的<!-- markdownlint-configure-file { ... } -->是内联配置注释，它仅关闭了line-length（MD013）规则，避免行长干扰本场景，同时保持MD041处于默认启用状态。

需要说明的是，该行引用的 Jekyll 文档页面为外部 URL，纯属测试内容；文章分析的依据是仓库内的实现与测试快照。

MD041 规则的判定逻辑：什么情况下报错

MD041的官方说明位于 doc/md041.md，其目的是"确保文档拥有标题"。默认情况下，规则要求文档的第一行是顶级标题（HTML 中的h1），否则报告错误。例如：

This is a document without a heading

修复方式是添加顶级标题：

# Document Heading This is a document with a top-level heading

该规则同样接受 HTML 标题（常用于 README 用图片作为标题的场景，如<h1 align="center"><img src="..."/></h1>），也允许通过allow_preamble: true容忍标题前存在目录等前置文本。

三个可配置参数

从 doc/md041.md 可以完整看到该规则的参数定义：

其中front_matter_title是理解本场景的关键：如果 Front Matter 中存在匹配该正则的属性，规则视为"文档已有标题"，不再要求正文首行是 H1。若想完全禁用 Front Matter 作为标题来源，可将其设置为空字符串""；若使用非title的属性名，则需提供自定义正则。

源码验证：frontMatterHasTitle 与 token 遍历

MD041的实现在 lib/md041.mjs，其核心流程分两步。

第一步是调用frontMatterHasTitle检查 Front Matter 是否携带标题：

if ( !frontMatterHasTitle( params.frontMatterLines, params.config.front_matter_title ) ) { ... }

该辅助函数定义在 helpers/helpers.cjs，实现非常精简：默认正则^\s*"?title"?\s*[:=]（忽略大小写），对每一行 Front Matter 做测试；当front_matter_title配置为空字符串（falsy）时，ignoreFrontMatter置为true，直接跳过 Front Matter 判定：

const ignoreFrontMatter = (frontMatterTitlePattern !== undefined) && !frontMatterTitlePattern; const frontMatterTitleRe = new RegExp( String(frontMatterTitlePattern || "^\\s*\"?title\"?\\s*[:=]"), "i" ); return !ignoreFrontMatter && frontMatterLines.some((line) => frontMatterTitleRe.test(line));

注意默认正则中的[:=]同时匹配 YAML 风格（title: ...）和 TOML 风格（title = ...），而可选的引号"?则兼容带引号的键名。

第二步，若 Front Matter 没有标题，则遍历 micromark 解析出的 token 寻找第一个内容节点，lib/md041.mjs 的判定规则是：

• 遇到atxHeading/setextHeading时，若其级别不等于level（默认1）则记录错误行号并中断；
• 遇到 HTML 流中的h1~h6标签（通过getHtmlFlowTagName提取标签名）时，若标签级别不匹配同样报错并中断；
• 若遇到其他内容 token，且allow_preamble为false，则直接报错中断（这正是front-matter-no-title-no-h1.md第 7 行命中的分支）；
• nonContentTokens集合与 HTML 流注释（isHtmlFlowComment）会被跳过，因此注释、空行等不会触发规则。

在我们分析的场景中：Front Matter 只有notitle而没有title，frontMatterHasTitle返回false；正文第一行是普通段落文本而非任何级别标题，于是规则在第 7 行抛出MD041错误，测试标记{MD041}与快照中的lineNumber: 7完全对应。

Front Matter 的解析与剥离：三种格式支持

params.frontMatterLines从何而来？答案在 lib/markdownlint.mjs 的removeFrontMatter函数中：lint 主流程会先尝试在文档开头匹配 Front Matter，若命中则将其从正文内容中剥离，并单独存入frontMatterLines（供各规则读取），同时记录行偏移，使错误行号仍然指向原始文件的行。

Front Matter 的匹配正则frontMatterRe定义于 helpers/helpers.cjs，它同时支持三种常见格式：

/((^---[^\S\r\n\u2028\u2029]*$[\s\S]+?^---\s*)|(^\+\+\+[^\S\r\n\u2028\u2029]*$[\s\S]+?^(\+\+\+|\.\.\.)\s*)|(^\{[^\S\r\n\u2028\u2029]*$[\s\S]+?^\}\s*))(\r\n|\r|\n|$)/m

• --- ... ---：YAML Front Matter（Jekyll、Hugo 等静态站点常用）；
• +++ ... +++或+++ ... ...：TOML Front Matter（如 pandoc）；
• { ... }：JSON Front Matter。

仓库测试目录中可找到对应的覆盖用例，例如 YAML 风格的 front-matter-title-h1.md、TOML 风格的 front-matter-title-pandoc.md、JSON 风格的 front-matter-title-json.md。此外，lib/markdownlint.mjs 显示用户也可以通过frontMatter选项传入自定义正则来替换默认匹配器。

同族场景对比：四种 Front Matter 变体

仓库用一系列命名相似的测试文件对MD041的 Front Matter 行为做了矩阵式覆盖，理解它们能帮你准确预判实际项目的检查结果：

1. 有 title、无 H1——通过。front-matter-title-no-h1.md 与本文场景唯一区别是第 3 行为title: "Welcome to Jekyll!"。快照 markdownlint-test-scenarios.mjs.snapshot 显示其errors为空数组：frontMatterHasTitle命中默认正则，规则直接跳过。

2. 无 title、有 H1——通过。front-matter-no-title-h1.md 在正文首行给出# Top level heading，虽然 Front Matter 没有title，但正文 H1 满足规则要求，快照同样为errors: []。

3. 空字符串禁用 Front Matter——即使有 title 也报错。front-matter-empty-title-no-h1.md 的 Front Matter 明明含有title，但内联配置把front_matter_title设为""，规则被迫忽略 Front Matter，正文无 H1 时第 7 行触发MD041。这印证了 doc/md041.md 中"禁用 Front Matter 判定"的用法。

4. 自定义属性名——报错变为通过。front-matter-alt-title-no-h1.md 使用alternate="Welcome to Jekyll!"作为标题来源，并通过内联配置指定front_matter_title: "^\\s*alternate="，于是无 H1 也不报错。JSON 变体 front-matter-alt-title-json.md 展示了带引号键的写法"^\\s*\"alternate\"\\s*:"。

除MD041外，frontMatterHasTitle同样被MD025（single-title，见 lib/md025.mjs）和MD001（heading-increment，见 lib/md001.mjs）复用，因此调整front_matter_title会影响这些规则的 Front Matter 标题识别行为（例如 front-matter-alt-title-h1.md 演示了MD025与自定义正则的联动）。

场景测试机制：如何验证"第 7 行报 MD041"

front-matter-no-title-no-h1.md之所以能成为可靠证据，是因为 test/markdownlint-test-scenarios.mjs 的测试框架会读取该文件并用lint({ "files": [file] })实际执行检查，然后比对两套结果：

• 标记断言：文件中的{MD041}标记被正则/\{(MD\d+)(?::([-+]?)(\d+))?\}/g解析，可带行号偏移（如{MD041:+2}）指向期望命中的行；
• 快照比对：实际输出与 markdownlint-test-scenarios.mjs.snapshot 中记录的errors/fixed字段逐一比对。

该场景的快照精确记录了期望结果：ruleNames为["MD041", "first-line-heading", "first-line-h1"]，lineNumber为7，errorContext为"Front matter from [Jekyll docu..."（截断的上下文），severity为"error"。同时快照给出了修复后的完整内容（将违规行改写为带{MD041}标记的原文，说明该规则本身不可自动修复，fixInfo为null）。

这意味着：任何修改MD041实现的行为都必须保证该场景继续在第 7 行报错，否则快照测试即失败——它是规则行为的一道强约束回归测试。

实战修复方案与配置建议

针对"Front Matter 无 title 且正文无 H1"的MD041报错，可依据项目约束选择以下方案：

1. 补充正文顶级标题（最稳妥）：在 Front Matter 之后、正文首行添加# 文档标题。这是默认配置下的推荐做法，因为 H1 同时服务于文档可访问性与搜索引擎。
2. 在 Front Matter 中补充title字段：让默认正则^\s*title\s*[:=]命中，例如title: "Welcome to Jekyll!"。
3. 自定义标题属性名：若 Front Matter 使用alternate、notitle等非标准键，通过配置或内联注释指定front_matter_title正则，如"^\\s*alternate="。注意正则中的反斜杠在 JSON 配置中需写为\\s。
4. 完全禁用 Front Matter 判定：设front_matter_title为""，强制正文必须出现 H1（适合希望以正文标题为唯一标题来源的文档集）。
5. 放宽级别或允许前置文本：外部系统已提供h2标题时设level: 2；文档标题前存在目录/引言等固定内容时设allow_preamble: true。

若希望在front-matter-no-title-no-h1.md这类 Jekyll 博客文章场景中"正文无 H1 也不报错"，最贴合的做法是在 Front Matter 中增加title字段（方案 2）；若layout模板本身已渲染标题，也可用内联配置关闭MD041：

<!-- markdownlint-configure-file { "first-line-heading": false } -->

小结

test/front-matter-no-title-no-h1.md表面上只是 10 行测试数据，实则是MD041规则"Front Matter 标题豁免机制"的最直接证据：标题判定优先级为front_matter_title正则命中 > 正文 H1/HTML 标题 > 报错，三个层次分别由 helpers/helpers.cjs 的frontMatterHasTitle与 lib/md041.mjs 的 token 遍历实现，并由场景测试与快照机制 markdownlint-test-scenarios.mjs 持续守护。掌握这一链路，你就能在真实项目中精准诊断"为什么有 Front Matter 还报首行标题错误"，并针对性地选用allow_preamble、front_matter_title、level三个参数完成配置。

• 开发工具
• 代码质量
• Lint
• 静态分析