Pandoc RST 阅读器标题解析实战层级推断、文档元数据提取与显式引用锚点issue #4240【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc本文以 pandoc 仓库中的命令测试 test/command/4240.md 为切入点深入讲解 Pandoc 的 reStructuredTextRST阅读器如何推断标题层级、如何从文档头部提取 title/subtitle 元数据以及.. _name:显式引用标记如何影响标题 ID 与文档结构。读完本文你将理解pandoc -f rst -s -t native输出中 Header、Meta、Span 等 AST 结构的由来并能对照源码定位每一层转换背后的实现逻辑。测试文件速览一份 RST 解析的输入-输出标本test/command/4240.md 是 Pandoc 的命令行测试command test文件其格式为第一行以%声明要执行的命令随后是输入文档^D表示输入结束最后是期望的标准输出。测试的核心命令是% pandoc -f rst -s -t native即以 RST 为输入格式-f rst输出 Pandoc 内部 AST 的 native 表示-t native-s表示 standalone 模式生成包含完整元数据的文档。输入文档包含以下关键结构一个用双线装饰的Title和一个用-双线装饰的Subtitle四个分别用、-、~、~单线装饰的header1~header4两个显式引用标记.. _id:与.. _id2:、.. _id3:分别附着在header3与header4之前。期望输出中文档元数据Meta包含title与subtitle两项值均为MetaInlines正文块依次为Header 1、Header 2、Header 3、Header 3且header3获得标识符idheader4获得标识符id3并在文本中插入一个空的Span (id2,[],[])。这一输出看似简单背后却涉及 RST 阅读器中最核心的三套机制。标题层级是如何推断的下划线字符与层级状态表RST 规范中标题由标题文本加上下划线可选再叠加顶线构成且同一层级必须使用同一个下划线字符。Pandoc 的 RST 阅读器在 src/Text/Pandoc/Readers/RST.hs 中实现了两套解析器doubleHeaderL469-L500处理顶线 文本 底线的双线标题并会校验标题文本长度不超过顶线长度singleHeaderL503-L537处理文本 底线的单线标题解析前会先lookAhead确认下一行是完整下划线避免把普通段落的第一行误判为标题。允许作为下划线的字符定义在 L75-L76 的underlineCharsunderlineChars :: [Char] underlineChars !\#$%()*,-./:;?[\\]^_{|}~标题层级level的分配由解析器状态中的stateHeaderTable维护。以doubleHeader为例L473-L484let headerTable stateHeaderTable state let (headerTable,level) case elemIndex (DoubleHeader c) headerTable of Just ind - (headerTable, ind 1) Nothing - (headerTable [DoubleHeader c], length headerTable 1)这里的关键在于单线标题与双线标题共用同一个层级状态表表中元素是DoubleHeader c或SingleHeader c两种构造子。elemIndex从头查找字符是否出现过出现过则复用其层级否则追加到表尾并获得一个新层级。由于查找的是整个混合列表双线已经占据 level 1、双线-占据 level 2 之后单线首次出现时只能排到 level 3单线-为 level 4单线~为 level 5第二次出现的单线~复用 level 5。由此可以完整复现输入文档的初始标题层级标题装饰方式下划线字符初始 levelTitle双线1Subtitle双线-2header1单线3header2单线-4header3单线~5header4单线~5文档标题与副标题的提取titleTransform 与标题提升初始解析得到[Header 1 Title, Header 2 Subtitle, Header 3, Header 4, Header 5, Header 5]而最终输出中 header1~header4 变成了 level 1/2/3/3。这一变化来自文档级转换titleTransformL129-L146titleTransform (bs, meta) let (bs, meta) case bs of (Header 1 _ head1:Header 2 _ head2:rest) | not (any (isHeader 1) rest || any (isHeader 2) rest) - (promoteHeaders 2 rest, setMeta title (fromList head1) $ setMeta subtitle (fromList head2) meta) (Header 1 _ head1:rest) | not (any (isHeader 1) rest) - (promoteHeaders 1 rest, setMeta title (fromList head1) meta) _ - (bs, meta)其逻辑是如果文档以 level 1 标题开头且后面不再出现 level 1则把该标题提升为title元数据如果 level 1 之后紧跟 level 2 标题且 rest 中不再出现 level 1/2则同时把 level 2 标题提升为subtitle元数据随后用promoteHeadersL119-L123把所有剩余标题的层级整体上移level 减 1 或 2。对本测试而言Title/Subtitle 恰好满足 level 1 level 2 且其余部分不再有 level 1/2 的条件因此二者被提取为MetaInlines而promoteHeaders 2把 header1~header4 从 3/4/5/5 提升为 1/2/3/3——这正是期望输出中的Header 1~Header 3序列。也就是说期望输出中的标题层级并不是原始解析值而是经过文档标题提取 整体提升二次变换后的结果。titleTransform还会顺带处理紧随其后的定义列表metaFromDefList把定义列表键值对转为元数据并支持把authors归并为author、按分号拆分多个作者。这也是 RST 文档常用docinfo写法的实现基础。显式引用标记与标题锚点anchor 为何用 Span 而非 DivRST 中.. _name:形式的行是显式引用目标explicit target通常用于定义超链接锚点或交叉引用。在 Pandoc 的 RST 阅读器中.. _name:直接出现在某块之前时由anchor解析器处理L1395-L1416anchor try $ do refs - referenceNames blanklines forM_ refs $ \rawkey - updateState $ \s - s { stateKeys M.insert (toKey rawkey) ((# rawkey,), nullAttr) (stateKeys s) } b - block ... case B.toList b of [Header lev (_,classes,kvs) txt] - case reverse refs of [] - return b (r:rs) - return $ B.singleton $ Header lev (r,classes,kvs) (txt map emptySpanWithId rs) -- we avoid generating divs for headers, -- because it hides them from promoteHeader, see #4240 _ - return $ foldr addDiv b refs这段代码揭示了三个重要行为每个引用名都会被登记到stateKeys表中映射为#name形式的内部链接目标供后续的引用链接reference link解析使用如果.. _name:后紧跟的是一个标题块则不生成包裹性的 Div而是直接改写标题的属性reverse refs中的第一个名字成为标题的 id其余名字以空SpanemptySpanWithId追加进标题文本如果后跟的不是标题才用foldr addDiv把引用名包成多个嵌套 Div。注释中的see #4240正是本测试文件的来历早期实现对标题也统一包裹 Div而titleTransform/promoteHeaders通过模式匹配Header块来识别文档标题一旦 Header 被 Div 隐藏文档标题提取与整体层级提升就会失效。修复方案即对标题直接改 id、不包 div。据此可以逐条还原测试输出.. _id:位于header3之前 → 只有单个引用reverse refs [id]因此header3的标识符为id输出Header 3 (id,[],[]) [Str header3].. _id2:、.. _id3:连续位于header4之前 →refs [id2,id3]reverse后第一个是id3故header4的 id 为id3而id2作为空 Span 追加进标题内联内容输出Header 3 (id3,[],[]) [Str header4, Span (id2,[],[]) []]。注意这里 id 归属遵循后写者胜的规则当多个引用目标附着于同一标题时最后一个在reverse后居首成为标题 id其余退化为 Span。而位于普通段落、图片等非标题块前的引用则会被包装成嵌套 Div并同时保留其作为交叉引用锚点的注册。如何复现与验证测试文件本身即可作为复现实验的输入。将 test/command/4240.md 中%行之后、^D之前的内容保存为sample.rst然后执行pandoc -f rst -s -t native sample.rst输出的Meta、Header、Span结构应与测试文件期望部分一致。也可仅查看某个具体格式的渲染结果例如pandoc -f rst -t html观察header3/header4是否分别带有idid与idid3的锚点属性从而验证显式引用目标确实进入了标题标识符。若想深入调试可关注 src/Text/Pandoc/Readers/RST.hs 中stateHeaderTable层级状态表、stateKeys引用目标表与registerHeader的配合前者决定了同字符同层级的 RST 标题规则后者在生成标题时注册去重后的自动标识符二者共同保证-t html等输出中锚点 ID 的唯一性与可引用性。小结通过剖析 test/command/4240.md 这一份麻雀虽小、五脏俱全的命令测试我们可以把 Pandoc RST 阅读器的标题体系归纳为三层层级推断层doubleHeader/singleHeader依据stateHeaderTable混合计数将不同的下划线字符映射为稳定的层级保证 RST 文档全篇一致元数据提取层titleTransformpromoteHeaders把文档头部标题 副标题提升为title/subtitle元数据并将剩余标题整体上移锚点归属层anchor对标题前的.. _name:引用直接改写标题 id、用空 Span 承载多余引用issue #4240 的修复对非标题块则退化为 Div 包裹同时所有引用名都会注册进stateKeys以供交叉引用。理解这三层机制后无论是排查 RST 文档标题层级异常、title/subtitle 提取失败还是分析引用锚点丢失问题都可以直接定位到对应的解析函数与状态表快速找到症结所在。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc RST 阅读器标题解析实战：层级推断、文档元数据提取与显式引用锚点（issue 4240）
Pandoc RST 阅读器标题解析实战层级推断、文档元数据提取与显式引用锚点issue #4240【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc本文以 pandoc 仓库中的命令测试 test/command/4240.md 为切入点深入讲解 Pandoc 的 reStructuredTextRST阅读器如何推断标题层级、如何从文档头部提取 title/subtitle 元数据以及.. _name:显式引用标记如何影响标题 ID 与文档结构。读完本文你将理解pandoc -f rst -s -t native输出中 Header、Meta、Span 等 AST 结构的由来并能对照源码定位每一层转换背后的实现逻辑。测试文件速览一份 RST 解析的输入-输出标本test/command/4240.md 是 Pandoc 的命令行测试command test文件其格式为第一行以%声明要执行的命令随后是输入文档^D表示输入结束最后是期望的标准输出。测试的核心命令是% pandoc -f rst -s -t native即以 RST 为输入格式-f rst输出 Pandoc 内部 AST 的 native 表示-t native-s表示 standalone 模式生成包含完整元数据的文档。输入文档包含以下关键结构一个用双线装饰的Title和一个用-双线装饰的Subtitle四个分别用、-、~、~单线装饰的header1~header4两个显式引用标记.. _id:与.. _id2:、.. _id3:分别附着在header3与header4之前。期望输出中文档元数据Meta包含title与subtitle两项值均为MetaInlines正文块依次为Header 1、Header 2、Header 3、Header 3且header3获得标识符idheader4获得标识符id3并在文本中插入一个空的Span (id2,[],[])。这一输出看似简单背后却涉及 RST 阅读器中最核心的三套机制。标题层级是如何推断的下划线字符与层级状态表RST 规范中标题由标题文本加上下划线可选再叠加顶线构成且同一层级必须使用同一个下划线字符。Pandoc 的 RST 阅读器在 src/Text/Pandoc/Readers/RST.hs 中实现了两套解析器doubleHeaderL469-L500处理顶线 文本 底线的双线标题并会校验标题文本长度不超过顶线长度singleHeaderL503-L537处理文本 底线的单线标题解析前会先lookAhead确认下一行是完整下划线避免把普通段落的第一行误判为标题。允许作为下划线的字符定义在 L75-L76 的underlineCharsunderlineChars :: [Char] underlineChars !\#$%()*,-./:;?[\\]^_{|}~标题层级level的分配由解析器状态中的stateHeaderTable维护。以doubleHeader为例L473-L484let headerTable stateHeaderTable state let (headerTable,level) case elemIndex (DoubleHeader c) headerTable of Just ind - (headerTable, ind 1) Nothing - (headerTable [DoubleHeader c], length headerTable 1)这里的关键在于单线标题与双线标题共用同一个层级状态表表中元素是DoubleHeader c或SingleHeader c两种构造子。elemIndex从头查找字符是否出现过出现过则复用其层级否则追加到表尾并获得一个新层级。由于查找的是整个混合列表双线已经占据 level 1、双线-占据 level 2 之后单线首次出现时只能排到 level 3单线-为 level 4单线~为 level 5第二次出现的单线~复用 level 5。由此可以完整复现输入文档的初始标题层级标题装饰方式下划线字符初始 levelTitle双线1Subtitle双线-2header1单线3header2单线-4header3单线~5header4单线~5文档标题与副标题的提取titleTransform 与标题提升初始解析得到[Header 1 Title, Header 2 Subtitle, Header 3, Header 4, Header 5, Header 5]而最终输出中 header1~header4 变成了 level 1/2/3/3。这一变化来自文档级转换titleTransformL129-L146titleTransform (bs, meta) let (bs, meta) case bs of (Header 1 _ head1:Header 2 _ head2:rest) | not (any (isHeader 1) rest || any (isHeader 2) rest) - (promoteHeaders 2 rest, setMeta title (fromList head1) $ setMeta subtitle (fromList head2) meta) (Header 1 _ head1:rest) | not (any (isHeader 1) rest) - (promoteHeaders 1 rest, setMeta title (fromList head1) meta) _ - (bs, meta)其逻辑是如果文档以 level 1 标题开头且后面不再出现 level 1则把该标题提升为title元数据如果 level 1 之后紧跟 level 2 标题且 rest 中不再出现 level 1/2则同时把 level 2 标题提升为subtitle元数据随后用promoteHeadersL119-L123把所有剩余标题的层级整体上移level 减 1 或 2。对本测试而言Title/Subtitle 恰好满足 level 1 level 2 且其余部分不再有 level 1/2 的条件因此二者被提取为MetaInlines而promoteHeaders 2把 header1~header4 从 3/4/5/5 提升为 1/2/3/3——这正是期望输出中的Header 1~Header 3序列。也就是说期望输出中的标题层级并不是原始解析值而是经过文档标题提取 整体提升二次变换后的结果。titleTransform还会顺带处理紧随其后的定义列表metaFromDefList把定义列表键值对转为元数据并支持把authors归并为author、按分号拆分多个作者。这也是 RST 文档常用docinfo写法的实现基础。显式引用标记与标题锚点anchor 为何用 Span 而非 DivRST 中.. _name:形式的行是显式引用目标explicit target通常用于定义超链接锚点或交叉引用。在 Pandoc 的 RST 阅读器中.. _name:直接出现在某块之前时由anchor解析器处理L1395-L1416anchor try $ do refs - referenceNames blanklines forM_ refs $ \rawkey - updateState $ \s - s { stateKeys M.insert (toKey rawkey) ((# rawkey,), nullAttr) (stateKeys s) } b - block ... case B.toList b of [Header lev (_,classes,kvs) txt] - case reverse refs of [] - return b (r:rs) - return $ B.singleton $ Header lev (r,classes,kvs) (txt map emptySpanWithId rs) -- we avoid generating divs for headers, -- because it hides them from promoteHeader, see #4240 _ - return $ foldr addDiv b refs这段代码揭示了三个重要行为每个引用名都会被登记到stateKeys表中映射为#name形式的内部链接目标供后续的引用链接reference link解析使用如果.. _name:后紧跟的是一个标题块则不生成包裹性的 Div而是直接改写标题的属性reverse refs中的第一个名字成为标题的 id其余名字以空SpanemptySpanWithId追加进标题文本如果后跟的不是标题才用foldr addDiv把引用名包成多个嵌套 Div。注释中的see #4240正是本测试文件的来历早期实现对标题也统一包裹 Div而titleTransform/promoteHeaders通过模式匹配Header块来识别文档标题一旦 Header 被 Div 隐藏文档标题提取与整体层级提升就会失效。修复方案即对标题直接改 id、不包 div。据此可以逐条还原测试输出.. _id:位于header3之前 → 只有单个引用reverse refs [id]因此header3的标识符为id输出Header 3 (id,[],[]) [Str header3].. _id2:、.. _id3:连续位于header4之前 →refs [id2,id3]reverse后第一个是id3故header4的 id 为id3而id2作为空 Span 追加进标题内联内容输出Header 3 (id3,[],[]) [Str header4, Span (id2,[],[]) []]。注意这里 id 归属遵循后写者胜的规则当多个引用目标附着于同一标题时最后一个在reverse后居首成为标题 id其余退化为 Span。而位于普通段落、图片等非标题块前的引用则会被包装成嵌套 Div并同时保留其作为交叉引用锚点的注册。如何复现与验证测试文件本身即可作为复现实验的输入。将 test/command/4240.md 中%行之后、^D之前的内容保存为sample.rst然后执行pandoc -f rst -s -t native sample.rst输出的Meta、Header、Span结构应与测试文件期望部分一致。也可仅查看某个具体格式的渲染结果例如pandoc -f rst -t html观察header3/header4是否分别带有idid与idid3的锚点属性从而验证显式引用目标确实进入了标题标识符。若想深入调试可关注 src/Text/Pandoc/Readers/RST.hs 中stateHeaderTable层级状态表、stateKeys引用目标表与registerHeader的配合前者决定了同字符同层级的 RST 标题规则后者在生成标题时注册去重后的自动标识符二者共同保证-t html等输出中锚点 ID 的唯一性与可引用性。小结通过剖析 test/command/4240.md 这一份麻雀虽小、五脏俱全的命令测试我们可以把 Pandoc RST 阅读器的标题体系归纳为三层层级推断层doubleHeader/singleHeader依据stateHeaderTable混合计数将不同的下划线字符映射为稳定的层级保证 RST 文档全篇一致元数据提取层titleTransformpromoteHeaders把文档头部标题 副标题提升为title/subtitle元数据并将剩余标题整体上移锚点归属层anchor对标题前的.. _name:引用直接改写标题 id、用空 Span 承载多余引用issue #4240 的修复对非标题块则退化为 Div 包裹同时所有引用名都会注册进stateKeys以供交叉引用。理解这三层机制后无论是排查 RST 文档标题层级异常、title/subtitle 提取失败还是分析引用锚点丢失问题都可以直接定位到对应的解析函数与状态表快速找到症结所在。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考