企业官网建设流程全解析

• 开发工具
• CLI

Setext 标题（Setext Heading）是 Markdown 中两类标题语法之一，用正文下方的---（二级）或===（一级）下划线标记标题级别，与 ATX 的#前缀语法互补。本仓库的基准测试样本 block-lheading.md 以一段仅 7 行的最小化输入，集中覆盖了 Setext 标题的命中与拒绝两条路径，是理解 lheading 块级规则 行为的最佳切入点。读完本文，你将掌握 markdown-it 中 Setext 标题的完整解析流程、与段落/分隔线（hr）规则的优先级博弈、相关边界条件，以及如何运行 benchmark 验证这类语法结构的解析吞吐量。

一、样本文件解析：block-lheading.md 里究竟测了什么

先完整展示关联文档 benchmark/samples/block-lheading.md 的原始内容：

heading --- heading =================================== not a heading ----------------------------------- text

该样本按顺序构造了三个独立场景，每一个都对应 lheading.ts 中的一条关键代码路径：

场景 3 是样本的精髓：----------------------------------- text这一行虽然以一串-开头，但后面跟了文本text，不满足“下划线行除标记与空白外不得有其他内容”的条件，因此整块回退为段落解析。从基准测试角度看，这代表一种“看似 Setext 标题实则不是”的最坏情况——解析器必须完成整行扫描后放弃标题判定，再走一遍段落流程，是衡量解析器退化路径性能的理想探针。

用仓库自带实现渲染该样本（见 benchmark/implementations/current/index.mjs，即markdownit({ html: true, linkify: true, typographer: true })默认配置），得到的 HTML 为：

<h2>heading</h2> <h1>heading</h1> <p>not a heading ----------------------------------- text</p>

这正是 CommonMark 规范对 Setext 标题行为的直接体现。

二、核心实现：lheading.ts 的逐段判定流程

Setext 标题的块级规则位于 src/rules_block/lheading.ts，函数签名与同目录其他块规则一致：

export default function lheading (state: StateBlock, startLine: number, endLine: number/*, silent */): boolean

2.1 前置缩进检查

规则开头（lheading.ts 第 9-10 行）先做缩进过滤：

// if it's indented more than 3 spaces, it should be a code block if (state.sCount[startLine] - state.blkIndent >= 4) { return false }

state.sCount记录每行展开 Tab 后的实际缩进列数，state.blkIndent是当前块内容所需的基础缩进（如列表项内）。缩进达到 4 列及以上时按 CommonMark 规则应解释为代码块，直接返回false，把机会让给code规则。

2.2 借用 paragraph 的终止规则集

接着是一个精妙的复用设计（lheading.ts 第 7-13 行）：

const terminatorRules = state.md.block.ruler.getRules('paragraph') ... state.parentType = 'paragraph' // use paragraph to match terminatorRules

markdown-it 的 Ruler 为每条规则登记了alt列表（见 parser_block.ts 第 19-37 行 中_rules数组），alt中含'paragraph'的规则（table、fence、blockquote、hr、list、html_block、heading 等）都可以在无空行的情况下“打断”一个段落。lheading 直接复用这套规则集来判断下划线行之后的内容是否需要提前终止扫描，而不是另写一套逻辑。

2.3 逐行扫描与下划线标记识别

核心循环（lheading.ts 第 20-58 行）从startLine + 1开始逐行推进，直到空行或 EOF：

for (; nextLine < endLine && !state.isEmpty(nextLine); nextLine++) { // this would be a code block normally, but after paragraph // it's considered a lazy continuation regardless of what's there if (state.sCount[nextLine] - state.blkIndent > 3) { continue } // Check for underline in setext header if (state.sCount[nextLine] >= state.blkIndent) { let pos = state.bMarks[nextLine] + state.tShift[nextLine] const max = state.eMarks[nextLine] if (pos < max) { marker = state.src.charCodeAt(pos) if (marker === 0x2D/* - */ || marker === 0x3D/* = */) { pos = state.skipChars(pos, marker) pos = state.skipSpaces(pos) if (pos >= max) { level = (marker === 0x3D/* = */ ? 1 : 2) break } } } } ... }

这段代码的判定要点：

• 行内深度缩进（> 3）的行被跳过，作为段落的 lazy continuation 处理；
• 取下划线的判定基于 StateBlock 预计算好的行缓存：bMarks是行起始偏移、tShift是首个非空白字符偏移、eMarks是行结束偏移，全部在 state_block.ts 第 65-98 行 的构造函数中一次性扫描建立，使解析可以按行号快速跳转而无需回溯；
• 首字符必须是-（0x2D）或=（0x3D）；
• 用skipChars跳过连续同字符标记、skipSpaces跳过尾随空白后，若位置已到行尾（pos >= max），则判定为有效下划线：=对应 level 1，-对应 level 2（lheading.ts 第 40 行）。

这正是样本场景 3 被拒绝的原因：--- text在跳过-与空格后，pos仍指向text，pos < max，条件不成立，level保持 0，最终落入段落分支。

2.4 终止规则检查与 token 生成

若当前行不是有效下划线，循环会依次以 silent 模式调用 terminatorRules（lheading.ts 第 51-58 行），任一规则判定该行能开启新块则提前终止扫描；state.sCount[nextLine] < 0的 blockquote 特判则跳过已由引用规则处理过的行。

扫描结束后若level仍为 0，恢复parentType并返回false（lheading.ts 第 61-65 行）。否则用asciiTrim截取正文内容，并依次生成三个 token（lheading.ts 第 67-81 行）：

const token_o = state.push('heading_open', `h${level}`, 1) token_o.markup = String.fromCharCode(marker!) token_o.map = [startLine, state.line] const token_i = state.push('inline', '', 0) token_i.content = content token_i.map = [startLine, state.line - 1] token_i.children = [] const token_c = state.push('heading_close', `h${level}`, -1) token_c.markup = String.fromCharCode(marker!)

heading_open/heading_close的 tag 分别为h1/h2，中间是携带正文的 inline token，其内容会在后续 rules_inline 阶段继续解析为行内元素。

三、与兄弟规则的协作：ATX、段落与分隔线

3.1 与 ATX 标题（#）的分工

ATX 标题由 heading.ts 处理，它在行首统计#数量（1~6 级），要求#后跟空白或行尾。两者在 parser_block.ts 的规则链 中的注册顺序为：heading（ATX）在前、lheading在后、paragraph兜底。ATX 标题可以出现在任意行首（包括打断段落），而 Setext 标题本质上是“段落 + 下划线”的组合，这正是两者最本质的行为差异。

3.2 与段落规则的“打断”机制

paragraph.ts 与 lheading 共享同一套终止规则扫描框架（paragraph.ts 第 7-29 行）。当一段文本下方出现---/===时，lheading规则在规则链中先于paragraph命中并消费该行，段落规则因此不会触发；而一旦 lheading 判定失败（如样本场景 3），控制权才流转到 paragraph，把两行合并为一个普通段落。两个规则对parentType的临时切换（都设为'paragraph'）保证了它们在嵌套容器（列表、引用）内的行为一致。

3.3 与分隔线（hr）的优先级

---同时是分隔线（thematic break）的合法标记，hr.ts 会接受整行仅由-/*/_及空白组成的行。CommonMark 规范明确规定：当一行-既可作分隔线又可作 Setext 下划线时，Setext 标题解释优先。这与规则链的注册顺序一致——hr在 parser_block.ts 第 30 行 注册于lheading之前，但 hr 只有在 lheading 未命中（例如当前行不是段落上下文）时才生效；而Foo\n---这种输入会由 lheading 先消费为 h2 而非<hr>。测试夹具 commonmark_extras.txt 中[foo]: /url 'title\n - - -\n'一例也印证了这种打断关系：引用定义被 hr 打断，而不是被误判为标题。

四、CommonMark 规范要点与边界条件

CommonMark 规范（test/fixtures/commonmark/spec.txt 中第 1319-1343 行附近的定义）对 Setext 标题有如下约束，均可在 lheading.ts 实现中找到对应：

• 下划线定义：=或-的连续序列，缩进不超过 3 个空格，可带任意尾随空格或 Tab（对应skipChars+skipSpaces后要求pos >= max）；
• 级别映射：=为一级标题，-为二级标题（对应 level 1/2 的赋值）；
• 不能打断段落：Setext 标题紧跟段落时需要空行分隔，否则段落会吞并下划线行成为正文（对应“正文行被跳过、仅当下划线行满足全部条件才成立”的扫描逻辑）；
• 不能是 lazy continuation：列表项或引用内，下划线行若属于 lazy continuation 则失效。这一条在 commonmark_extras.txt 中有两组成对回归测试：

Setext header text supports lazy continuations: - foo bar === → <h1>foo\nbar</h1> But setext header underline doesn't: - foo bar === → 普通列表项文本（不构成标题）

前者验证正文可跨行 lazy continuation，后者验证下划线行本身不能作为 lazy continuation——两组用例精确刻画了 Setext 标题在嵌套容器中的行为边界。

五、样本在 benchmark 框架中的角色与运行方式

5.1 样本如何被加载

benchmark/benchmark.mjs 启动时会扫描benchmark/samples/目录下所有文件（第 17-35 行），每个样本用 tinybench、current、current-commonmark、marked）都注册为被测任务，统一以impl.code.run(content.string)方式渲染同一份样本内容。样本名取文件名去掉扩展名，即block-lheading。

5.2 运行与筛选

命令行支持按正则筛选样本（benchmark.mjs 第 56-76 行 的select与第 78-99 行的run）：

# 运行全部样本 node benchmark/benchmark.mjs # 只运行 Setext 标题样本 node benchmark/benchmark.mjs block-lheading # 模糊匹配所有 block 类样本 node benchmark/benchmark.mjs '^block-'

输出会先列出选中的样本，再逐样本报告每个实现的吞吐量，格式为ops/sec ±相对误差% (采样次数)，例如文档 docs/benchmark.md 中记录的 README 样本输出形如：

Sample: README.md (7774 bytes) > current x 743 ops/sec ±0.84% (97 runs sampled)

[!NOTE] 上述数字是 docs/benchmark.md 与 benchmark/samples/README.md 中记录的特定机器（MB Pro Retina 2013）历史示例，仅用于说明输出格式；真实数据请在自己机器上重新运行获得。另据 docs/benchmark.md 的说明，current-commonmark实现使用了简化链接规范化以做“更公平”对比，与完整版存在约 1.5× 差距，这是特性差异而非性能缺陷。

5.3 样本设计意图

benchmark/samples/中同类样本（block-heading.md 覆盖 ATX 标题的各级与否定场景、block-hr.md 覆盖分隔线变体、block-lheading.md 覆盖 Setext 标题）共同构成按语法类别划分的微基准集。block-lheading.md的价值在于：用最少字节同时覆盖命中（---/===）与拒绝（--- text）两条路径，前者考验标记扫描的最快路径，后者考验“扫描整行后失败回退”的退化路径，两者结合能较真实地反映 lheading 规则在典型文档中的整体开销。

六、小结

从 benchmark/samples/block-lheading.md 这 7 行样本出发，可以完整还原 markdown-it 的 Setext 标题解析闭环：

• 语法层面：=下划线 →<h1>，-下划线 →<h2>，下划线行不允许任何非空白尾随内容；
• 实现层面：lheading.ts 借助 StateBlock 的预计算行缓存实现按行跳转，通过复用 paragraph 的终止规则集完成边界扫描，失败时优雅回退给 paragraph.ts；
• 规范层面：与 hr 的优先级、与段落的打断关系、lazy continuation 限制均在 spec.txt 与 commonmark_extras.txt 中有据可查；
• 验证层面：benchmark.mjs 提供按名筛选的微基准运行方式，node benchmark/benchmark.mjs block-lheading即可一键复测。

读懂这一条规则的完整链路，也就掌握了 markdown-it 块级解析器“规则链 + 共享状态 + 终止规则复用”三大设计支柱的典型样本，这对后续阅读列表、引用、表格等其他块级规则同样适用。

• 开发工具
• CLI