企业官网建设流程全解析

• 文档
• 开发工具
• CLI

本篇文章以 pandoc 仓库中的命令测试用例 test/command/5714.md 为切入点，深入讲解 pandoc Markdown 读取器在处理 ATX 标题（#开头）与 Setext 标题（=====/-----下划线）时对换行符的边界约束：标题内容在换行处立即终止，绝不跨行吞并后续文本。读完本文，你将理解该行为的底层实现机制（stateAllowLineBreaks解析状态）、它对标题文本与自动标识符（identifier）生成的影响，以及如何通过pandoc -t native与仓库命令测试套件自行复现和验证。

一、测试用例原文解读：test/command/5714.md

该文件是 pandoc 的golden command test（命令回归测试），完整内容如下：

% pandoc -t native # hi _a b_ # hi _c c ^D [ Header 1 ( "hi-_a" , [] , [] ) [ Str "hi" , Space , Str "_a" ] , Para [ Str "b_" ] , Header 1 ( "hi-_c" , [] , [] ) [ Str "hi" , Space , Str "_c" ] , Para [ Str "c" ] ]

其结构遵循test/command/目录下所有命令测试的统一格式：开闭的 ``` 围栏内模拟一次完整的终端会话——

1. % pandoc -t native：执行的命令，即以native格式（Pandoc AST 的 Haskell 字面量表示）输出解析结果；
2. 随后到^D（EOF）之间的文本是标准输入（stdin）中的 Markdown 源文档；
3. ^D之后的内容是期望的精确输出，测试驱动代码会逐字比对实际输出与期望输出，任何差异都会导致该用例失败。

输入与期望 AST 的对应关系

输入共 4 行有效内容，被解析为2 个 ATX 标题 + 2 个普通段落：

这个结果看似平淡，实则蕴含一条关键规则：标题文本只取#之后到本行行尾之间的内容。# hi _a后面的b_虽然与标题之间没有空行分隔，但它并不会被并入标题行内元素列表，而是独立成为正文段落。

二、行为背后的源码实现：换行即标题边界

这条规则对应 pandoc 变更记录中的一条修复：

Headers: don't parse content over newline boundary (#5714). —— changelog.md

即 issue #5714 修复了旧版本中标题解析可能越过换行边界继续吞并后续内容的缺陷。实现位于 Markdown 读取器 src/Text/Pandoc/Readers/Markdown.hs：

2.1 ATX 标题：解析期间关闭换行内联

atxHeader（Markdown.hs#L529-L547）的核心逻辑如下：

atxHeader = try $ do level <- fmap length (atxChar >>= many1 . char) notFollowedBy $ guardEnabled Ext_fancy_lists >> (char '.' <|> char ')') -- this would be a list guardDisabled Ext_space_in_atx_header <|> notFollowedBy nonspaceChar skipSpaces (text, raw) <- withRaw $ do oldAllowLineBreaks <- stateAllowLineBreaks <$> getState updateState $ \st -> st{ stateAllowLineBreaks = False } res <- trimInlinesF . mconcat <$> many (notFollowedBy atxClosing >> inline) updateState $ \st -> st{ stateAllowLineBreaks = oldAllowLineBreaks } return res attr <- atxClosing ...

关键步骤是：

• atxChar决定标题标记符（默认#；启用literate_haskell扩展时为=）；
• guardDisabled Ext_space_in_atx_header <|> notFollowedBy nonspaceChar保证#与正文之间必须有空白，且不能是列表起始（如#.、#)会被当作列表而非标题）；
• 解析标题内联内容（inline）之前，先把stateAllowLineBreaks置为False，解析结束后恢复原值——这是整个换行边界规则的枢纽；
• atxClosing（Markdown.hs#L549-L558）负责处理行尾可选的#闭合符、属性（header_attributes）或 MMD 风格标识符，并消费空行。

2.2 Setext 标题同样受限

setextHeader（Markdown.hs#L579-L600）采用同样的手法，在解析=====/-----下划线之上的文本行时同样将stateAllowLineBreaks置为False，并在完成后恢复。也就是说，无论 ATX 还是 Setext 风格，标题内容一律被限制在单个物理行内。

2.3endline解析器：换行何时可成为行内元素

stateAllowLineBreaks这个状态位在换行处理endline（Markdown.hs#L1824-L1839）中被消费：

endline = try $ do newline notFollowedBy blankline getState >>= guard . stateAllowLineBreaks -- ← 关键守卫 ...

endline负责把行尾换行解析为行内空格（或启用hard_line_breaks时解析为LineBreak）。当stateAllowLineBreaks = False时，guard直接使该分支失败，于是inline的组合子链在换行处不再匹配，标题内联解析随即终止——换行成为不可逾越的标题边界。

该状态在解析状态结构中定义（src/Text/Pandoc/Parsing/State.hs#L48），默认值为True（State.hs#L142），仅在标题这类需要"单行约束"的上下文中被临时关闭。

三、换行边界对标题标识符的影响

测试用例中两个标题的标识符分别为hi-_a与hi-_c，这同样不是偶然，而是由标题标识符生成管线决定：

1. 标题解析完成后，registerHeader会调用uniqueIdent（src/Text/Pandoc/Shared.hs#L671-L682）为标题生成不重复的自动标识符；若基础标识符已被占用，则追加-1、-2……后缀；
2. uniqueIdent内部调用inlineListToIdentifier（Shared.hs#L531-L544），先把行内元素 stringify 为纯文本，再交给textToIdentifier（Shared.hs#L547-L569）；
3. 默认（非 GFM）规则下：小写化 → 过滤标点（保留_、-、.，见isAllowedPunct）→ 按空白切分后用-连接。

因此标题文本hi _a生成hi-_a：内部空格转为连字符，而下划线_被保留——这也是为什么测试用例特意选择带下划线的标题，以验证标识符生成在标题边界约束下依然精确对应"单行文本"。

相关扩展对标识符的影响

• gfm_auto_identifiers：标识符生成改用 GFM 规则（空格转-、保留_及组合类标点、不再丢弃前导非字母字符，见 Shared.hs#L552-L568）；
• ascii_identifiers：将非 ASCII 字符转换为 ASCII 转写；
• mmd_header_identifiers/header_attributes：允许在标题行内显式指定{#id}，此时显式标识符优先于自动生成值（atxClosing与setextHeaderEnd中的option逻辑）。

四、如何复现与验证

本仓库为只读镜像，你可以用任意已安装的 pandoc 二进制在本地验证同样的行为：

printf '# hi _a\nb_\n\n# hi _c\nc\n' | pandoc -t native

输出应与 test/command/5714.md 中^D之后的期望 AST 完全一致。若想验证"修复前"的差异，可以比较：如果不施加换行边界，b_会被并入第一个标题，输出会变成Header 1 ... [Str "hi", Space, Str "_a", Space, Str "b_"]，这正是 issue #5714 所描述的问题行为。

仓库内的命令测试由 test/Tests/Command.hs 驱动，test/command/目录下每个*.md文件即一个独立用例；Markdown 读取器的单元测试则位于 test/Tests/Readers/Markdown.hs。配合test/command/5714.md这类回归用例，可以确保"标题不跨行"这一行为在后续迭代中不被无意破坏。

五、小结：一条边界规则，三处联动实现

test/command/5714.md虽只有 16 行，却完整覆盖了一条贯穿 Markdown 读取器核心的边界规则及其回归保障：

1. 解析层：atxHeader/setextHeader在解析标题内联内容时临时关闭stateAllowLineBreaks（Markdown.hs#L537-L541）；
2. 换行层：endline通过guard . stateAllowLineBreaks让换行在标题上下文中不可作为行内元素（Markdown.hs#L1828）；
3. 标识符层：uniqueIdent/textToIdentifier基于"单行标题文本"生成稳定的自动标识符（Shared.hs#L671-L682）。

理解这条规则，对于排查 Markdown 文档中标题异常合并、标识符与预期不符等问题，以及在基于 pandoc 的二次开发中保持标题语义正确性，都具有直接的参考价值。

• 文档
• 开发工具
• CLI