文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载导读本文以 pandoc 官方命令测试用例 test/command/4594.md 为切入点系统讲解 Markdown 文档中嵌入 LaTeX 环境如figure与内联命令如\textbf、\emph时pandoc 如何通过raw_tex扩展将其识别为 RawBlock / RawInline 节点并在转换为 LaTeX 时原样输出。读完本文你将掌握raw_tex的启用方式、解析边界、底层实现路径以及它在跨格式转换中的行为差异能直接在 Markdown 源中安全地混排 LaTeX 代码。从一个命令测试用例说起在 pandoc 仓库的test/command/4594.md中记录了一组典型的「Markdown 内嵌 LaTeX」转换场景% pandoc -f markdown -t latex Some **bold** text here. \begin{figure}[htbp] \centering \def\svgwidth{\columnwidth} \import{img/}{vectors.pdf_tex} \caption{Some caption.} \end{figure} Some *italic* text here. ^D Some \textbf{bold} text here. \begin{figure}[htbp] \centering \def\svgwidth{\columnwidth} \import{img/}{vectors.pdf_tex} \caption{Some caption.} \end{figure} Some \emph{italic} text here.该用例验证了两个行为Markdown 标记被正常解析**bold**与*italic*被解析为Strong/Emph内联元素再渲染为 LaTeX 的\textbf{...}与\emph{...}LaTeX 环境原样透传\begin{figure}[htbp] ... \end{figure}这一整块没有被当作 Markdown 逐行解析而是作为一个整体成为原始 LaTeX 块原封不动地出现在输出中。这正是raw_tex扩展的核心职责把源文档中无法用 Markdown 表示的 TeX 内容原样保留交给支持它的 writer。raw_tex 是什么开启开关与默认状态raw_texAllow raw TeX (other than math)是 pandoc 的解析扩展之一定义于 src/Text/Pandoc/Extensions.hs 的数据类型Extension它在 pandoc 的markdown变体markdown_strict、markdown_phpextra、markdown_mmd、markdown_github、markdown中默认启用相关集合定义在getAll markdown等分支它也是 LaTeX / Beamer / ConTeXt 等「latex 系」reader 的默认扩展见getAll latex、getAll beamer、getAll context可通过-f markdown-raw_tex关闭或-f markdownraw_tex强制开启。使用pandoc -f markdown -t latex input.md即可复现测试用例中的行为要禁用原样透传则改用pandoc -f markdown-raw_tex -t latex。MANUAL.txt 中 Extension:raw_tex一节明确说明除了markdown该扩展还可作用于textile、commonmark等格式并且禁用raw_html/raw_tex在转换到不支持这些原始内容的格式如 docx时往往能得到更干净的结果。解析与透传的底层实现Reader 端rawTeXBlock 与 rawLaTeXInline在 Markdown readersrc/Text/Pandoc/Readers/Markdown.hs中有两个关键函数分别处理块级与行内 TeXrawTeXBlock约 L1161先guardEnabled Ext_raw_tex检查开关随后尝试连续匹配 ConTeXt 环境或 LaTeX 原始块最终以B.rawBlock tex构造 RawBlock 节点格式统一记为tex源码注释解释为 tex because it might be context若内容全为空白则丢弃rawLaTeXInline约 L2139同样先guardEnabled Ext_raw_tex再用rawLaTeXInline解析单个命令并以B.rawInline tex生成 RawInline 节点。也就是说环境中\begin...\end之间的内容整体进入 RawBlock而不会退回 Markdown 逐行解析——这正是测试用例中\def\svgwidth、\import、\caption等命令保持原样的原因。真正的 TeX 分词器rawLaTeXBlock / rawLaTeXInline上述两个函数复用的是 src/Text/Pandoc/Readers/LaTeX.hs 中的底层解析器rawLaTeXBlock约 L164lookAhead (try (char \\ letter))要求内容以反斜杠开头随后调用rawLaTeXParser尝试匹配latexEnv完整环境、macroDef、atLetterSection等命中后返回原始 TeX 文本rawLaTeXInline约 L207同样要求以\开头尝试解析\input{...}、单条命令及其参数等返回行内原始文本。这保证了只有结构完整的 LaTeX 片段才会被当作原始内容不满足条件的文本会回落到普通 Markdown 解析路径。Writer 端RawBlock 的格式过滤在 LaTeX writersrc/Text/Pandoc/Writers/LaTeX.hs中blockToLaTeX对 RawBlock 的处理约 L581当 RawBlock 的格式为latex或tex或在 beamer 模式下为beamer时原样输出其内容return $ literal x否则报告BlockNotRendered并输出空内容。因此从-f markdown读入的格式为tex的 RawBlock在-t latex时能够无损透传。同时MANUAL.txt 明确指出行内 LaTeX 在输出到Markdown、LaTeX、Emacs Org mode、ConTeXt之外的格式时会被忽略——即从 markdown 转到 HTML、docx 等格式时\textbf{...}这类行内命令不会出现在输出中。实战在 Markdown 中嵌入 LaTeX 的推荐用法结合测试用例与 MANUAL.txt 的说明可以将实践要点归纳如下行内命令直接写。例如This result was proved in \cite{jones.1967}.会被原样传给 LaTeX/ConTeXt writer可用于 BibTeX 引用、交叉引用等环境整块嵌入。\begin{tabular}...\end{tabular}、\begin{figure}...\end{figure}这类块级环境会被识别为原始 LaTeX 块其内部不会被当作 Markdown 解析适合放置由绘图工具如 Inkscape导出的\import{img/}{vectors.pdf_tex}式矢量插图代码注意格式兼容性。默认 markdown 下raw_tex已启用若源文档含有大量 LaTeX 而目标格式不支持如 docx、HTML建议用-f markdown-raw_tex关闭避免产生不可预期的原始文本更灵活的场景用 raw_attribute。如果需要精确指定某段内容的原始格式可以使用raw_attribute扩展例如{ms} ... 或...{html}这在多格式混排时比raw_tex的隐式识别更可控。如何用仓库证据验证命令测试运行 test/command/4594.md 中的命令可复现「环境原样保留 加粗/斜体转为\textbf/\emph」的完整输出Reader 源码src/Text/Pandoc/Readers/Markdown.hs 的rawTeXBlock/rawLaTeXInline及Ext_raw_tex开关检查LaTeX 分词src/Text/Pandoc/Readers/LaTeX.hs 的rawLaTeXBlock/rawLaTeXInlineWriter 过滤src/Text/Pandoc/Writers/LaTeX.hs 的blockToLaTeX中 RawBlock 分支扩展开关定义src/Text/Pandoc/Extensions.hs 的Ext_raw_tex及各格式默认扩展集合官方文档MANUAL.txt 的 Extension:raw_tex与raw_attribute小节。通过这五处证据链可以确认raw_tex的完整工作流程Markdown reader 借助 LaTeX 分词器识别 TeX 片段 → 构造 RawBlock/RawInline 节点 → LaTeX writer 按格式过滤后原样输出而 4594 号测试用例正是这一流程的最小可复现验证。赞分享文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载相关推荐pandoc HTML 阅读器 raw_tex 扩展深度解析从 1126 号命令测试看 LaTeX 环境与引用的保留机制pandoc HTML 阅读器 raw_tex 扩展深度解析从 1126 号命令测试看 LaTeX 环境与引用的保留机制 导读 pandoc 的 HTML 阅文档开发工具CLIPandoc 从 LaTeX 读取 raw_tex 扩展\noindent 行内命令的保留机制与源码级解析Pandoc 从 LaTeX 读取 raw_tex 扩展 \noindent 行内命令的保留机制与源码级解析 导读 本篇技术指南以 Pandoc 仓库中的命令文档开发工具CLIPandoc 原始 LaTeX 解析边界探秘\start 命令的 raw_tex 处理与 Markdown 读取器解析逻辑Pandoc 原始 LaTeX 解析边界探秘 \start 命令的 raw_tex 处理与 Markdown 读取器解析逻辑 导读 在 Pandoc 的 Ma文档开发工具CLI上一篇Switch-Fightstick项目解密基于LUFA库的任天堂Switch自定义手柄开发全解析下一篇Apache OpenWhisk开发环境搭建本地调试与测试的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考