pandoc 将 HTML 高亮代码块转换为 GFM 围栏代码块hljs 类与 language- 前缀的处理机制【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读在从 HTML 文档迁移到 GitHub 风格 MarkdownGFM的工作流中一个高频需求是把语法高亮器如 highlight.js产出的precode classhljs language-bash代码块原样还原为可读的围栏代码块。pandoc 的 HTML 阅读器与 Markdown 书写器在这一环节有明确、可复现的行为它会合并pre与code上的属性、剥离language-前缀并输出为带语言标注的反引号围栏。本文以 pandoc 仓库中的命令测试用例 test/command/11701.md 为线索结合 HTML 阅读器 与 Markdown 书写器 的源码实现完整讲解这一转换链路并给出可复制的命令行操作与边界行为说明。测试用例原文最小可复现的转换场景仓库中 test/command/11701.md 是 pandoc 自带的回归测试用例golden test完整内容如下% pandoc -f html -t gfm pre stylewhite-space: pre-wrapcode classhljs language-bashecho hello /code/pre ^D bash echo hello 它描述了这样一次转换输入格式HTML-f html包含一个典型的 highlight.js 输出片段——外层pre带有行内样式white-space: pre-wrap内层code带有classhljs language-bash输出格式GFM-t gfm预期结果输出为以三个反引号包裹的围栏代码块 bash内容为echo hello。这个用例虽短却浓缩了三个关键技术点代码块属性的跨标签合并、hljs等纯装饰类的处理、language-前缀到语言标注的映射。亲手复现在终端运行这条命令将测试用例保存为输入文件后可以直接用 pandoc 复现在 pandoc 仓库根目录下执行pandoc -f html -t gfm EOF pre stylewhite-space: pre-wrapcode classhljs language-bashecho hello /code/pre EOF预期输出echo hello注意输出围栏后的语言标注为bash而非hljs language-bash。如果去掉language-bash而只保留classhljspandoc 会退化为输出一个不带语言标注的围栏代码块这说明hljs本身不被当作语言信息处理只有language-*形式的类才会被识别为语法语言。底层原理HTML 阅读器如何解析代码块转换的第一步发生在 HTML 阅读器中。在 src/Text/Pandoc/Readers/HTML.hs 里pre标签由解析函数pCodeBlock处理L686-L704其核心逻辑分为三步合并pre与code的属性解析器依次匹配pre与code两个开标签然后通过attr codeAttr把两者的属性拼接起来。注释明确说明“pres attributes take precedence”pre 的属性优先级更高因为toAttr在遇到重复属性时保留第一个而拼接顺序是 pre 在前。这正是测试用例里pre stylewhite-space: pre-wrap与code class...能够协同生效的原因——它们分别贡献style和class互不冲突。剥离language-前缀modifyClasses对class属性中的每个词调用stripLanguagePrefix其实现为T.stripPrefix language-L691。于是language-bash变成bash从而在后续书写器中直接对应 GFM 的语言标注。规整内容文本manyTill pAny (pCloses pre | eof)收集pre内部的所有内容并把br标签转换为换行符见tagToTextL706-L709最后用T.unsnoc去掉末尾多余的换行构造出CodeBlockB.codeBlockWith attr result。值得注意的是解析器的调度位置L239pre - pCodeBlock | pPreBlock即优先尝试按代码块解析失败时回退到通用预格式化块pPreBlock解析。这一设计保证了普通pre文本段落不会被误判。HTML 阅读器测试套件 test/Tests/Readers/HTML.hs 中有一组针对性测试与上述逻辑一一对应L130-L140, testGroup code block [ test html attributes in pre code element $ precode id\a\ class\python\\nprint(hi)\n/code/pre ? codeBlockWith (a, [python], []) \nprint(hi) , test html attributes in pre take precedence $ pre id\c\code id\d\print(hi mom!)\n/code/pre ? codeBlockWith (c, [], []) print(hi mom!) ]第一个用例验证属性合并id与class分别来自code与pre第二个用例验证重复属性冲突时 pre 优先idc胜出。这些测试从另一个角度印证了 11701 用例中属性的流向。输出侧Markdown 书写器如何生成围栏代码块转换的第二步由 Markdown 书写器完成。在 src/Text/Pandoc/Writers/Markdown.hs 的blockToMarkdown中CodeBlock的分支L580-L611按以下优先级决定输出形态若目标变体为CommonmarkGFM 属于此类或启用了backtick_code_blocks扩展输出反引号围栏代码块否则若启用了fenced_code_blocks扩展输出波浪线~围栏代码块都不满足时退化为 4 空格缩进tab stop的缩进式代码块。因此-t gfm走的是第一条路径产出 bash格式。围栏长度的选择也很讲究endlineLen会扫描代码内容统计以或~~~开头的行将围栏长度至少定为“内容中最长围栏长度 1”初始最小值为 3从而避免围栏与内容冲突——这是把任意 HTML 代码块安全搬进 Markdown 的关键细节。语言标注的生成由getLangFromClassesL969-L976完成-- Identify the class in a list of classes that corresponds to -- the language syntax. language-X turns to X. getLangFromClasses :: WriterOptions - [Text] - Maybe Text getLangFromClasses opts cs case find (language- T.isPrefixOf) cs of Just x - Just (T.drop 9 x) Nothing - case [x | x - cs, isJust (lookupSyntax x (writerSyntaxMap opts))] of (x:_) - Just x [] - Nothing它优先查找形如language-X的类并把language-前缀去掉T.drop 9恰好去掉前缀的 9 个字符找不到时再借助writerSyntaxMap检查某个类是否匹配已配置的语法映射表lookupSyntax。结合阅读器侧的stripLanguagePrefixhljs类在两侧都不会被误认为语言——这正是 11701 用例输出 bash而非 hljs language-bash的完整原因。实用要点把这一机制用在你的 HTML→Markdown 工作流中基于以上源码行为可以总结出以下可操作的迁移经验高亮器输出可直接转换由 highlight.js、Prism 等工具渲染出的precode classhljs language-xxx结构pandoc 开箱即用pandoc -f html -t gfm无需预处理去类名language-前缀会被自动还原为 GFM 语言标注。hljs等纯样式类会被丢弃阅读器只剥离language-前缀hljs会作为普通 class 进入内部Attr而 GFM 书写时语言标注仅由getLangFromClasses从language-*类或语法映射中推导因此hljs不会出现在输出围栏上。若你希望保留自定义类需要显式开启fenced_code_attributes或attributes扩展见 L604-L611 中attrs的生成逻辑。pre与code属性取并集、冲突时 pre 优先若两个标签都带class它们会按词合并若出现id等重复属性pre上的值胜出。迁移前可据此预判转换结果。尾随换行与围栏安全由引擎兜底阅读器会剔除代码内容末尾的换行书写器会自动加长围栏以避免与内容中的反引号行冲突因此 HTML 里换行混乱的代码块也能得到规范的 GFM 输出。如果还想验证更多 HTML→Markdown 的边界行为可直接阅读 test/Tests/Readers/HTML.hs 中的 code block 测试组或参考 test/command/ 目录下的其他回归用例它们是理解 pandoc 转换语义最权威的“活文档”。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pandoc 将 HTML 高亮代码块转换为 GFM 围栏代码块：hljs 类与 language- 前缀的处理机制
pandoc 将 HTML 高亮代码块转换为 GFM 围栏代码块hljs 类与 language- 前缀的处理机制【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读在从 HTML 文档迁移到 GitHub 风格 MarkdownGFM的工作流中一个高频需求是把语法高亮器如 highlight.js产出的precode classhljs language-bash代码块原样还原为可读的围栏代码块。pandoc 的 HTML 阅读器与 Markdown 书写器在这一环节有明确、可复现的行为它会合并pre与code上的属性、剥离language-前缀并输出为带语言标注的反引号围栏。本文以 pandoc 仓库中的命令测试用例 test/command/11701.md 为线索结合 HTML 阅读器 与 Markdown 书写器 的源码实现完整讲解这一转换链路并给出可复制的命令行操作与边界行为说明。测试用例原文最小可复现的转换场景仓库中 test/command/11701.md 是 pandoc 自带的回归测试用例golden test完整内容如下% pandoc -f html -t gfm pre stylewhite-space: pre-wrapcode classhljs language-bashecho hello /code/pre ^D bash echo hello 它描述了这样一次转换输入格式HTML-f html包含一个典型的 highlight.js 输出片段——外层pre带有行内样式white-space: pre-wrap内层code带有classhljs language-bash输出格式GFM-t gfm预期结果输出为以三个反引号包裹的围栏代码块 bash内容为echo hello。这个用例虽短却浓缩了三个关键技术点代码块属性的跨标签合并、hljs等纯装饰类的处理、language-前缀到语言标注的映射。亲手复现在终端运行这条命令将测试用例保存为输入文件后可以直接用 pandoc 复现在 pandoc 仓库根目录下执行pandoc -f html -t gfm EOF pre stylewhite-space: pre-wrapcode classhljs language-bashecho hello /code/pre EOF预期输出echo hello注意输出围栏后的语言标注为bash而非hljs language-bash。如果去掉language-bash而只保留classhljspandoc 会退化为输出一个不带语言标注的围栏代码块这说明hljs本身不被当作语言信息处理只有language-*形式的类才会被识别为语法语言。底层原理HTML 阅读器如何解析代码块转换的第一步发生在 HTML 阅读器中。在 src/Text/Pandoc/Readers/HTML.hs 里pre标签由解析函数pCodeBlock处理L686-L704其核心逻辑分为三步合并pre与code的属性解析器依次匹配pre与code两个开标签然后通过attr codeAttr把两者的属性拼接起来。注释明确说明“pres attributes take precedence”pre 的属性优先级更高因为toAttr在遇到重复属性时保留第一个而拼接顺序是 pre 在前。这正是测试用例里pre stylewhite-space: pre-wrap与code class...能够协同生效的原因——它们分别贡献style和class互不冲突。剥离language-前缀modifyClasses对class属性中的每个词调用stripLanguagePrefix其实现为T.stripPrefix language-L691。于是language-bash变成bash从而在后续书写器中直接对应 GFM 的语言标注。规整内容文本manyTill pAny (pCloses pre | eof)收集pre内部的所有内容并把br标签转换为换行符见tagToTextL706-L709最后用T.unsnoc去掉末尾多余的换行构造出CodeBlockB.codeBlockWith attr result。值得注意的是解析器的调度位置L239pre - pCodeBlock | pPreBlock即优先尝试按代码块解析失败时回退到通用预格式化块pPreBlock解析。这一设计保证了普通pre文本段落不会被误判。HTML 阅读器测试套件 test/Tests/Readers/HTML.hs 中有一组针对性测试与上述逻辑一一对应L130-L140, testGroup code block [ test html attributes in pre code element $ precode id\a\ class\python\\nprint(hi)\n/code/pre ? codeBlockWith (a, [python], []) \nprint(hi) , test html attributes in pre take precedence $ pre id\c\code id\d\print(hi mom!)\n/code/pre ? codeBlockWith (c, [], []) print(hi mom!) ]第一个用例验证属性合并id与class分别来自code与pre第二个用例验证重复属性冲突时 pre 优先idc胜出。这些测试从另一个角度印证了 11701 用例中属性的流向。输出侧Markdown 书写器如何生成围栏代码块转换的第二步由 Markdown 书写器完成。在 src/Text/Pandoc/Writers/Markdown.hs 的blockToMarkdown中CodeBlock的分支L580-L611按以下优先级决定输出形态若目标变体为CommonmarkGFM 属于此类或启用了backtick_code_blocks扩展输出反引号围栏代码块否则若启用了fenced_code_blocks扩展输出波浪线~围栏代码块都不满足时退化为 4 空格缩进tab stop的缩进式代码块。因此-t gfm走的是第一条路径产出 bash格式。围栏长度的选择也很讲究endlineLen会扫描代码内容统计以或~~~开头的行将围栏长度至少定为“内容中最长围栏长度 1”初始最小值为 3从而避免围栏与内容冲突——这是把任意 HTML 代码块安全搬进 Markdown 的关键细节。语言标注的生成由getLangFromClassesL969-L976完成-- Identify the class in a list of classes that corresponds to -- the language syntax. language-X turns to X. getLangFromClasses :: WriterOptions - [Text] - Maybe Text getLangFromClasses opts cs case find (language- T.isPrefixOf) cs of Just x - Just (T.drop 9 x) Nothing - case [x | x - cs, isJust (lookupSyntax x (writerSyntaxMap opts))] of (x:_) - Just x [] - Nothing它优先查找形如language-X的类并把language-前缀去掉T.drop 9恰好去掉前缀的 9 个字符找不到时再借助writerSyntaxMap检查某个类是否匹配已配置的语法映射表lookupSyntax。结合阅读器侧的stripLanguagePrefixhljs类在两侧都不会被误认为语言——这正是 11701 用例输出 bash而非 hljs language-bash的完整原因。实用要点把这一机制用在你的 HTML→Markdown 工作流中基于以上源码行为可以总结出以下可操作的迁移经验高亮器输出可直接转换由 highlight.js、Prism 等工具渲染出的precode classhljs language-xxx结构pandoc 开箱即用pandoc -f html -t gfm无需预处理去类名language-前缀会被自动还原为 GFM 语言标注。hljs等纯样式类会被丢弃阅读器只剥离language-前缀hljs会作为普通 class 进入内部Attr而 GFM 书写时语言标注仅由getLangFromClasses从language-*类或语法映射中推导因此hljs不会出现在输出围栏上。若你希望保留自定义类需要显式开启fenced_code_attributes或attributes扩展见 L604-L611 中attrs的生成逻辑。pre与code属性取并集、冲突时 pre 优先若两个标签都带class它们会按词合并若出现id等重复属性pre上的值胜出。迁移前可据此预判转换结果。尾随换行与围栏安全由引擎兜底阅读器会剔除代码内容末尾的换行书写器会自动加长围栏以避免与内容中的反引号行冲突因此 HTML 里换行混乱的代码块也能得到规范的 GFM 输出。如果还想验证更多 HTML→Markdown 的边界行为可直接阅读 test/Tests/Readers/HTML.hs 中的 code block 测试组或参考 test/command/ 目录下的其他回归用例它们是理解 pandoc 转换语义最权威的“活文档”。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考