Zettlr 的 Pandoc 桥接层pandoc-util 模块的 Reader/Writer 解析、格式映射与属性解析实战【免费下载链接】ZettlrYour One-Stop Publication Workbench项目地址: https://gitcode.com/GitHub_Trending/ze/ZettlrZettlr 是一款将 Markdown 编辑器与 Pandoc 深度整合的一站式出版工作台One-Stop Publication Workbench其导入导出能力的核心并不在 UI而在于source/common/pandoc-util/这一层薄而关键的桥接代码。本指南围绕该模块讲解 Zettlr 如何解析 Pandoc 风格的reader/writer属性串如markdownpipe_tables-smart、如何维护数百种读写格式与文件扩展名的映射以及如何把{width50%}这类链接属性解析为可渲染的 HTML。读完你将掌握这些工具函数的输入输出契约、背后的正则与解析策略以及它们如何被导出插件、导入管线和 Markdown 渲染器实际调用。模块定位Zettlr 与 Pandoc 之间的翻译层source/common/pandoc-util/README.md对该文件夹的定义非常简洁它包含 Zettlr 与 Pandoc 正确交互所需的各种工具——reader与writer属性解析器、默认文件类型default files types以及其他辅助能力。从源码结构看这一层被设计为纯 TypeScript 工具集不依赖 Electron 运行时因此可以在主进程、渲染进程与单元测试中共享pandoc-maps.ts维护 Pandoc 格式名 ↔ 可读字符串 / 文件扩展名的双向映射parse-reader-writer.ts解析与序列化 Pandoc 风格的reader/writer属性串parse-pandoc-attributes.ts解析 Pandoc 链接属性块如{#my-id .class width50%}为结构化对象。三者的职责互补前两个解决用哪个格式转换的问题第三个解决渲染时属性怎么写的问题共同支撑起导入、导出与编辑渲染三条业务线。Pandoc 格式双表可读名称与扩展名的权威映射PANDOC_READERS33 种输入格式的可读名称PANDOC_READERS是Recordstring, string把 Pandoc 内部格式名映射为用户可读字符串供 UI 下拉框、对话框与状态提示使用。关键条目包括Pandoc 格式名可读名称commonmark/commonmark_xCommonMark / CommonMark ExtgfmGitHub Markdownmarkdown/markdown_mmd/markdown_phpextra/markdown_strictMarkdown / MultiMarkdown / PHP Markdown Extra / Grubers Markdowndocx/odt/epub/rtfWord docx / OpenDocument Text / EPUB / Rich Text Formatlatex/org/rst/textileLaTeX / Org mode / reStructuredText / Textileipynb/csv/fb2/jiraJupyter Notebook / CSV / FictionBook2 / Jira/Confluencevimwiki/mediawiki/dokuwiki/tikiwiki/twiki各类 Wiki 标记语言PANDOC_WRITERS44 种输出格式覆盖幻灯片与出版场景PANDOC_WRITERS更为庞大除文本格式外还包含出版与演示输出docx、odt、epub/epub2/epub3、pptx、icmlInDesign、pdf、plain以及一组幻灯片格式beamer、revealjs、slideous、slidy、dzslides、s5。注意同一格式可对应多个别名如docbook/docbook4都显示为 DocBook 4html/html5都显示为 HTML 5映射时以后出现的条目为准。SUPPORTED_READERS编辑器原生可显示的白名单SUPPORTED_READERS是只读字符串数组只收录主编辑器能够直接展示的 8 种格式commonmark、commonmark_x、gfm、latex、markdown、markdown_mmd、markdown_phpextra、markdown_strict。导入管线会用它过滤默认配置文件确保候选配置的输出是编辑器能编辑的 Markdown 系格式见后文导入流程。WRITER2EXT输出格式 → 最常用扩展名导出插件需要为最终文件决定扩展名WRITER2EXT提供该映射。多数条目直观docx → docx、pdf → pdf但有几处值得注意的实现细节asciidoc → adoc、docbook → dbk、fb2 → db2、tei → odd采用社区约定而非格式名幻灯片格式带前缀revealjs → reveal.js.html、slidy → slidy.html、s5 → s5.html无标准扩展名的 Wiki 类格式直接用格式名dokuwiki、mediawiki、jira、xwiki、zimwikihaddock → hs源码注释指出其本质是 Haskell 源码。EXT2READER导入扩展名 → 候选 Reader 列表导入时用户选择的是文件扩展名Zettlr 需要反查可用的 Pandoc reader。EXT2READER是一对多映射md/markdown/rmd/mdx都指向 7 种 Markdown 系 readerdoc与docx都指向docxhtml/htm指向htmltex/latex指向latexwiki这一特殊扩展名聚合了 5 种 Wiki readervimwiki、twiki、tikiwiki、mediawiki、dokuwiki。源码注释特别说明csv、fb2、ipynb、jira没有作为显式导入扩展名暴露但用户可通过 All files 过滤器选择。reader/writer 属性串解析器parse-reader-writer.tsPandoc 允许通过格式名扩展名-扩展名语法微调解析/生成行为例如markdownpipe_tables-smart。Zettlr 将该语法封装为PandocReaderWriter接口与四个纯函数。数据结构interface PandocReaderWriter { name: string // 例如 markdown enabledExtensions: string[] // 例如 [pipe_tables] disabledExtensions: string[] // 例如 [smart] }接口注释强调enabledExtensions/disabledExtensions只记录显式启停的扩展与 Pandoc 默认开启/关闭的扩展无关。解析parseReaderWriter核心逻辑极简但高效若字符串不含/-直接整体作为name返回否则用split(/[-]/g)取第一段作为name再用matchAll(/([-][a-z0-9_])/gi)逐段归类。单元测试 pandoc-reader-writer.spec.ts 验证了三个典型输入markdown-smart → name: markdown, enabled: [], disabled: [smart] markdown-smartpipe_tables → name: markdown, enabled: [pipe_tables], disabled: [smart] markdown-pipe_tables-smart → name: markdown, enabled: [], disabled: [pipe_tables, smart]序列化与编辑readerWriterToString、enableExtension、disableExtensionreaderWriterToString按name 各ext 各-ext的顺序拼接回字符串测试覆盖markdown-smart-pipe_tables等输出enableExtension会先从disabledExtensions中移除同名扩展再追加到启用列表反之disableExtension对称操作保证同一扩展不会同时出现在两个数组中函数原地修改对象。Pandoc 链接属性解析器parse-pandoc-attributes.ts目标语法该模块对标 Pandoc 官方手册中link_attributes扩展的语法{#my-id .classes .other-classes keyvalue attrother value}ParsedPandocAttributes将之拆为三部分id#id、classes.class列表、propertieskeyvalue表。源码注释特别指出与 Pandoc 官方解析器不同本实现不区分HTML5 属性与自定义属性统一收进properties。解析策略与正则解析前先trim()并剥掉首尾的{/}。核心正则使用具名捕获组/#(?id[\w\-_])|\.(?class[\w\-_])|(?attr(?key[\w\-_])(?:(?quoted[^]*)|(?unquoted[^\s])))/g#(?id[\w\-_])捕获 id\.(?class[\w\-_])捕获 classkeyquoted或keyunquoted捕获属性带引号的值可含空格不带引号的值以空白为界。一个值得注意的细节对width和height若值为纯数字则自动补px单位50→50px这直接服务于图片尺寸的浏览器渲染。由单元测试固化的边界行为parse-pandoc-attributes.spec.ts 用 11 组用例锁定了行为契约以下边界必须知晓花括号可选width50%与{width50%}结果相同等号两侧不允许空格width 50%、{ width 50% }、{ width 50% }全部解析为空对象——正则要求key后紧跟数字宽高自动加 px{width10}→width: 10px{height75}→height: 75px引号值支持空格{keysome long value}完整保留畸形无引号值只取首词{keysome long value}→key: some后续 token 被吞并测试用例中输出没有多余的属性综合用例#some-id .class1 .class2 width50% height25 disabledfalse stylefont-size: 12px;完整解析出 id、两个 class 与 4 个属性。反向格式化formatPandocAttributes该函数把ParsedPandocAttributes重新拼回 HTML 可用的属性串id 输出为#idclasses 逐个加.前缀以空格连接properties 输出为keyvalue无值属性只输出 key。虽然当前未被单元测试直接覆盖但它与解析器构成完整的往返工具对。在仓库中的真实调用链pandoc-util 并非孤立代码以下五处调用点印证了它的实际价值。1. 默认导出插件writer 解析 扩展名映射default-exporter.ts 是WRITER2EXT与parseReaderWriter的直接消费者先用parseReaderWriter(options.profile.writer).name从配置中的 writer 属性串可能带ext/-ext剥离出纯格式名再查WRITER2EXT[parsedWriter] ?? parsedWriter得到扩展名随后基于首个源文件基名与可选的标题覆盖参数生成目标文件路径写入 defaults 文件并调用runPandoc执行转换。整个导出流程对用户选择的配置文件格式与扩展名完全透明。2. 导入管线EXT2READER 反查 SUPPORTED_READERS 过滤importer/index.ts 展示了完整导入决策树.textbundle/.textpack走专用导入器已是 Markdown 扩展名的文件直接copyFile其余文件经checkImportIntegrity得到availableReaders由EXT2READER驱动再过滤默认配置先SUPPORTED_READERS.includes(e.writer)限定输出必须是编辑器可编辑的 Markdown 系再按profile.reader匹配文件可用 reader候选多于一个时弹出对话框让用户选择配置文件最后把input-files/output-file写入临时 defaults 文件通过spawn(pandoc, [--defaults, ...])执行转换。若无任何匹配配置则提示需要先创建导入配置。3. 图片渲染器width/height 的 px 补全落到实处render-images.ts 调用parsePandocAttributes解析图片后面的属性块得到ParsedPandocAttributes后驱动渲染逻辑——这解释了width/height自动补px的动机编辑器在 HTML 渲染图片时需要合法尺寸单位。4. Pandoc div/span 渲染器通用属性块解析render-pandoc-div-span.ts 在渲染 Pandoc 的div/span元素时用同一解析器读取属性attrs.from/attrs.to是从 CodeMirror 状态切片出的属性文本区间把{#id .class keyvalue}转成渲染上下文实现 WYSIWYG 级别的属性展示。5. 资产窗口与默认配置编辑DefaultsTab.vue 提供默认配置文件defaults files的浏览、新建、重命名与编辑界面并针对受保护/无效配置给出警告提示——它是用户手工编辑reader/writer属性的入口也是 pandoc-util 输出被写回磁盘前的最后一站。结合 defaults 文件理解 reader/writer 的实际用法静态目录static/defaults/中存放了 Pandoc defaultsYAML配置模板例如Markdown.yaml、LaTeX.yaml、HTML to Markdown.yaml、Reveal.js.yaml、XeLaTeX PDF.yaml等覆盖导入与导出两类场景。在这些 YAML 中reader与writer字段正是 pandoc-util 所解析的属性串如writer: markdownraw_html与上述解析器形成完整闭环用户在配置界面改动writer字段 → 导出插件用parseReaderWriter剥离扩展名 → 用WRITER2EXT定扩展名 → pandoc 按--defaults文件执行。需要手工新增配置时可在static/defaults/目录参照现有模板创建并在资产窗口中加载。小结source/common/pandoc-util/是 Zettlr 与 Pandoc 协作的翻译层用 4 个文件解决了三类问题格式名↔可读名/扩展名的双向映射pandoc-maps.ts、reader/writer属性串的解析与增删扩展parse-reader-writer.ts、链接属性块的解析与反格式化parse-pandoc-attributes.ts。它们的正确性由 pandoc-reader-writer.spec.ts 与 parse-pandoc-attributes.spec.ts 两组测试固化并被导出插件、导入管线与两个 Markdown 渲染器直接消费。理解这一层是深入 Zettlr 导入导出架构、乃至扩展其格式支持的最短路径。【免费下载链接】ZettlrYour One-Stop Publication Workbench项目地址: https://gitcode.com/GitHub_Trending/ze/Zettlr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Zettlr 的 Pandoc 桥接层：pandoc-util 模块的 Reader/Writer 解析、格式映射与属性解析实战
Zettlr 的 Pandoc 桥接层pandoc-util 模块的 Reader/Writer 解析、格式映射与属性解析实战【免费下载链接】ZettlrYour One-Stop Publication Workbench项目地址: https://gitcode.com/GitHub_Trending/ze/ZettlrZettlr 是一款将 Markdown 编辑器与 Pandoc 深度整合的一站式出版工作台One-Stop Publication Workbench其导入导出能力的核心并不在 UI而在于source/common/pandoc-util/这一层薄而关键的桥接代码。本指南围绕该模块讲解 Zettlr 如何解析 Pandoc 风格的reader/writer属性串如markdownpipe_tables-smart、如何维护数百种读写格式与文件扩展名的映射以及如何把{width50%}这类链接属性解析为可渲染的 HTML。读完你将掌握这些工具函数的输入输出契约、背后的正则与解析策略以及它们如何被导出插件、导入管线和 Markdown 渲染器实际调用。模块定位Zettlr 与 Pandoc 之间的翻译层source/common/pandoc-util/README.md对该文件夹的定义非常简洁它包含 Zettlr 与 Pandoc 正确交互所需的各种工具——reader与writer属性解析器、默认文件类型default files types以及其他辅助能力。从源码结构看这一层被设计为纯 TypeScript 工具集不依赖 Electron 运行时因此可以在主进程、渲染进程与单元测试中共享pandoc-maps.ts维护 Pandoc 格式名 ↔ 可读字符串 / 文件扩展名的双向映射parse-reader-writer.ts解析与序列化 Pandoc 风格的reader/writer属性串parse-pandoc-attributes.ts解析 Pandoc 链接属性块如{#my-id .class width50%}为结构化对象。三者的职责互补前两个解决用哪个格式转换的问题第三个解决渲染时属性怎么写的问题共同支撑起导入、导出与编辑渲染三条业务线。Pandoc 格式双表可读名称与扩展名的权威映射PANDOC_READERS33 种输入格式的可读名称PANDOC_READERS是Recordstring, string把 Pandoc 内部格式名映射为用户可读字符串供 UI 下拉框、对话框与状态提示使用。关键条目包括Pandoc 格式名可读名称commonmark/commonmark_xCommonMark / CommonMark ExtgfmGitHub Markdownmarkdown/markdown_mmd/markdown_phpextra/markdown_strictMarkdown / MultiMarkdown / PHP Markdown Extra / Grubers Markdowndocx/odt/epub/rtfWord docx / OpenDocument Text / EPUB / Rich Text Formatlatex/org/rst/textileLaTeX / Org mode / reStructuredText / Textileipynb/csv/fb2/jiraJupyter Notebook / CSV / FictionBook2 / Jira/Confluencevimwiki/mediawiki/dokuwiki/tikiwiki/twiki各类 Wiki 标记语言PANDOC_WRITERS44 种输出格式覆盖幻灯片与出版场景PANDOC_WRITERS更为庞大除文本格式外还包含出版与演示输出docx、odt、epub/epub2/epub3、pptx、icmlInDesign、pdf、plain以及一组幻灯片格式beamer、revealjs、slideous、slidy、dzslides、s5。注意同一格式可对应多个别名如docbook/docbook4都显示为 DocBook 4html/html5都显示为 HTML 5映射时以后出现的条目为准。SUPPORTED_READERS编辑器原生可显示的白名单SUPPORTED_READERS是只读字符串数组只收录主编辑器能够直接展示的 8 种格式commonmark、commonmark_x、gfm、latex、markdown、markdown_mmd、markdown_phpextra、markdown_strict。导入管线会用它过滤默认配置文件确保候选配置的输出是编辑器能编辑的 Markdown 系格式见后文导入流程。WRITER2EXT输出格式 → 最常用扩展名导出插件需要为最终文件决定扩展名WRITER2EXT提供该映射。多数条目直观docx → docx、pdf → pdf但有几处值得注意的实现细节asciidoc → adoc、docbook → dbk、fb2 → db2、tei → odd采用社区约定而非格式名幻灯片格式带前缀revealjs → reveal.js.html、slidy → slidy.html、s5 → s5.html无标准扩展名的 Wiki 类格式直接用格式名dokuwiki、mediawiki、jira、xwiki、zimwikihaddock → hs源码注释指出其本质是 Haskell 源码。EXT2READER导入扩展名 → 候选 Reader 列表导入时用户选择的是文件扩展名Zettlr 需要反查可用的 Pandoc reader。EXT2READER是一对多映射md/markdown/rmd/mdx都指向 7 种 Markdown 系 readerdoc与docx都指向docxhtml/htm指向htmltex/latex指向latexwiki这一特殊扩展名聚合了 5 种 Wiki readervimwiki、twiki、tikiwiki、mediawiki、dokuwiki。源码注释特别说明csv、fb2、ipynb、jira没有作为显式导入扩展名暴露但用户可通过 All files 过滤器选择。reader/writer 属性串解析器parse-reader-writer.tsPandoc 允许通过格式名扩展名-扩展名语法微调解析/生成行为例如markdownpipe_tables-smart。Zettlr 将该语法封装为PandocReaderWriter接口与四个纯函数。数据结构interface PandocReaderWriter { name: string // 例如 markdown enabledExtensions: string[] // 例如 [pipe_tables] disabledExtensions: string[] // 例如 [smart] }接口注释强调enabledExtensions/disabledExtensions只记录显式启停的扩展与 Pandoc 默认开启/关闭的扩展无关。解析parseReaderWriter核心逻辑极简但高效若字符串不含/-直接整体作为name返回否则用split(/[-]/g)取第一段作为name再用matchAll(/([-][a-z0-9_])/gi)逐段归类。单元测试 pandoc-reader-writer.spec.ts 验证了三个典型输入markdown-smart → name: markdown, enabled: [], disabled: [smart] markdown-smartpipe_tables → name: markdown, enabled: [pipe_tables], disabled: [smart] markdown-pipe_tables-smart → name: markdown, enabled: [], disabled: [pipe_tables, smart]序列化与编辑readerWriterToString、enableExtension、disableExtensionreaderWriterToString按name 各ext 各-ext的顺序拼接回字符串测试覆盖markdown-smart-pipe_tables等输出enableExtension会先从disabledExtensions中移除同名扩展再追加到启用列表反之disableExtension对称操作保证同一扩展不会同时出现在两个数组中函数原地修改对象。Pandoc 链接属性解析器parse-pandoc-attributes.ts目标语法该模块对标 Pandoc 官方手册中link_attributes扩展的语法{#my-id .classes .other-classes keyvalue attrother value}ParsedPandocAttributes将之拆为三部分id#id、classes.class列表、propertieskeyvalue表。源码注释特别指出与 Pandoc 官方解析器不同本实现不区分HTML5 属性与自定义属性统一收进properties。解析策略与正则解析前先trim()并剥掉首尾的{/}。核心正则使用具名捕获组/#(?id[\w\-_])|\.(?class[\w\-_])|(?attr(?key[\w\-_])(?:(?quoted[^]*)|(?unquoted[^\s])))/g#(?id[\w\-_])捕获 id\.(?class[\w\-_])捕获 classkeyquoted或keyunquoted捕获属性带引号的值可含空格不带引号的值以空白为界。一个值得注意的细节对width和height若值为纯数字则自动补px单位50→50px这直接服务于图片尺寸的浏览器渲染。由单元测试固化的边界行为parse-pandoc-attributes.spec.ts 用 11 组用例锁定了行为契约以下边界必须知晓花括号可选width50%与{width50%}结果相同等号两侧不允许空格width 50%、{ width 50% }、{ width 50% }全部解析为空对象——正则要求key后紧跟数字宽高自动加 px{width10}→width: 10px{height75}→height: 75px引号值支持空格{keysome long value}完整保留畸形无引号值只取首词{keysome long value}→key: some后续 token 被吞并测试用例中输出没有多余的属性综合用例#some-id .class1 .class2 width50% height25 disabledfalse stylefont-size: 12px;完整解析出 id、两个 class 与 4 个属性。反向格式化formatPandocAttributes该函数把ParsedPandocAttributes重新拼回 HTML 可用的属性串id 输出为#idclasses 逐个加.前缀以空格连接properties 输出为keyvalue无值属性只输出 key。虽然当前未被单元测试直接覆盖但它与解析器构成完整的往返工具对。在仓库中的真实调用链pandoc-util 并非孤立代码以下五处调用点印证了它的实际价值。1. 默认导出插件writer 解析 扩展名映射default-exporter.ts 是WRITER2EXT与parseReaderWriter的直接消费者先用parseReaderWriter(options.profile.writer).name从配置中的 writer 属性串可能带ext/-ext剥离出纯格式名再查WRITER2EXT[parsedWriter] ?? parsedWriter得到扩展名随后基于首个源文件基名与可选的标题覆盖参数生成目标文件路径写入 defaults 文件并调用runPandoc执行转换。整个导出流程对用户选择的配置文件格式与扩展名完全透明。2. 导入管线EXT2READER 反查 SUPPORTED_READERS 过滤importer/index.ts 展示了完整导入决策树.textbundle/.textpack走专用导入器已是 Markdown 扩展名的文件直接copyFile其余文件经checkImportIntegrity得到availableReaders由EXT2READER驱动再过滤默认配置先SUPPORTED_READERS.includes(e.writer)限定输出必须是编辑器可编辑的 Markdown 系再按profile.reader匹配文件可用 reader候选多于一个时弹出对话框让用户选择配置文件最后把input-files/output-file写入临时 defaults 文件通过spawn(pandoc, [--defaults, ...])执行转换。若无任何匹配配置则提示需要先创建导入配置。3. 图片渲染器width/height 的 px 补全落到实处render-images.ts 调用parsePandocAttributes解析图片后面的属性块得到ParsedPandocAttributes后驱动渲染逻辑——这解释了width/height自动补px的动机编辑器在 HTML 渲染图片时需要合法尺寸单位。4. Pandoc div/span 渲染器通用属性块解析render-pandoc-div-span.ts 在渲染 Pandoc 的div/span元素时用同一解析器读取属性attrs.from/attrs.to是从 CodeMirror 状态切片出的属性文本区间把{#id .class keyvalue}转成渲染上下文实现 WYSIWYG 级别的属性展示。5. 资产窗口与默认配置编辑DefaultsTab.vue 提供默认配置文件defaults files的浏览、新建、重命名与编辑界面并针对受保护/无效配置给出警告提示——它是用户手工编辑reader/writer属性的入口也是 pandoc-util 输出被写回磁盘前的最后一站。结合 defaults 文件理解 reader/writer 的实际用法静态目录static/defaults/中存放了 Pandoc defaultsYAML配置模板例如Markdown.yaml、LaTeX.yaml、HTML to Markdown.yaml、Reveal.js.yaml、XeLaTeX PDF.yaml等覆盖导入与导出两类场景。在这些 YAML 中reader与writer字段正是 pandoc-util 所解析的属性串如writer: markdownraw_html与上述解析器形成完整闭环用户在配置界面改动writer字段 → 导出插件用parseReaderWriter剥离扩展名 → 用WRITER2EXT定扩展名 → pandoc 按--defaults文件执行。需要手工新增配置时可在static/defaults/目录参照现有模板创建并在资产窗口中加载。小结source/common/pandoc-util/是 Zettlr 与 Pandoc 协作的翻译层用 4 个文件解决了三类问题格式名↔可读名/扩展名的双向映射pandoc-maps.ts、reader/writer属性串的解析与增删扩展parse-reader-writer.ts、链接属性块的解析与反格式化parse-pandoc-attributes.ts。它们的正确性由 pandoc-reader-writer.spec.ts 与 parse-pandoc-attributes.spec.ts 两组测试固化并被导出插件、导入管线与两个 Markdown 渲染器直接消费。理解这一层是深入 Zettlr 导入导出架构、乃至扩展其格式支持的最短路径。【免费下载链接】ZettlrYour One-Stop Publication Workbench项目地址: https://gitcode.com/GitHub_Trending/ze/Zettlr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 插件、强制选项与开发服务器定制)
