My heading {-}【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc与 markdown # My heading {.unnumbered}完全等价。官方手册 MANUAL.txt 进一步说明unnumbered类的标题即使配合--number-sections也不会被编号若unlisted类与unnumbered同时出现则该标题不会出现在目录中并且明确指出该特性目前只在基于 LaTeX 和 HTML 的格式、PowerPoint 与 RTF 中实现。2.2 本测试为什么用{-}而不是{.unnumbered .unlisted}细心的读者会发现测试中只写了{-}期望输出却没有\addcontentsline被抑制——这看起来与unlisted 抑制目录的说法矛盾。实际上该测试的意图不是演示unlisted而是验证unnumbered标题在仍要写入 TOC 时目录条目的文本必须是去除链接后的纯文本这正是测试第一行注释的含义。unlisted的抑制逻辑在 LaTeX 写入器 中同样清晰可见$$ if unnumbered not unlisted then \\addcontentsline{toc} braces (text sectionType) braces txtNoLinksNoNotes else empty也就是说unnumbered为真、unlisted为假 → 生成\addcontentsline{toc}unlisted为真 → 什么都不生成标题彻底从目录消失。而什么情况下需要\addcontentsline取决于输出格式约定对 LaTeX 而言\section*这类星号变体默认不写入目录Pandoc 通过显式补发\addcontentsline让不编号与列目录可以共存。三、逐行拆解期望输出从 AST 到 LaTeX 代码为了让读者理解每个 LaTeX 片段从何而来下面按生成顺序逐段解析测试的期望输出。3.1\section*星号来自unnumbered测试输入是一级标题下划线式 setext 标题对应 AST 中的Header 1 [unnumbered]。在 sectionHeader 中let unnumbered unnumbered elem classes ... let star if unnumbered then text * else empty let title star optional contents ... text (\\:sectionType) title lablevel 1时sectionType section加上星号即为\section*。3.2\texorpdfstring{...}{...}标题文本与纯文本分离标题内容是一个链接渲染成 LaTeX 后是\url{http://example.com/}而字符串化的纯文本是http://example.com/。由于两者不同sectionHeader 会用\texorpdfstring包裹let contents if render Nothing txt plain then braces txt else braces (text \\texorpdfstring braces txt braces (literal plain))\texorpdfstring是hyperref宏包提供的命令其第一个参数用于排版正文保留\url{...}链接样式第二个参数用于 PDF 书签纯文本。这样既保证正文可点击跳转又保证书签字符串干净。3.3\label{httpexample.com}自动生成的锚点标题的 identifier 为httpexample.com由 Pandoc 从标题文本自动生成通过 labelFor 生成labelFor :: PandocMonad m Text - LW m (Doc Text) labelFor return empty labelFor ident do ref - literal fmap toLabel ident return $ text \\label braces reftoLabel负责把http://example.com/规范化成可作 LaTeX 标签的httpexample.com去除非字母数字字符。3.4\addcontentsline{toc}{section}{{http://example.com/}}去链接化的 TOC 条目这是本测试的主角。生成逻辑在 sectionHeader 中分为三步let lstNoNotes foldr (mappend . (\x - walkM removeInvalidInline x)) mempty lst txtNoNotes - inlineListToLaTeX lstNoNotes txtNoLinksNoNotes - inlineListToLaTeX (removeLinks lstNoNotes)其中removeLinks定义于 src/Text/Pandoc/Writers/Shared.hs其注释直截了当Convert links to spans; most useful when writing elements that must not contain links, e.g. to avoid nested links.removeLinks :: [Inline] - [Inline] removeLinks walk go where go (Link attr ils _) Span attr ils go x x同时removeInvalidInline还会剔除脚注Note、带 id 的Span和图片避免它们进入目录条目。于是目录条目内容从\url{http://example.com/}变为纯文本http://example.com/——这正是测试注释 unlinked 的含义也杜绝了目录中出现嵌套链接\addcontentsline的参数不应包含\url之类的可断行命令。最终由 sectionHeader 输出\\addcontentsline{toc} braces (text sectionType) braces txtNoLinksNoNotes即\addcontentsline{toc}{section}{{http://example.com/}}。注意内层多出的花括号{{http://example.com/}}来自braces函数用于保护文本内容。四、命令行实操复现与验证4.1 按测试原样复现在任意包含 Pandoc 的终端中执行pandoc --tolatex EOF http://example.com/ {-} EOF预期输出与测试期望一致\section*{\texorpdfstring{\url{http://example.com/}}{http://example.com/}}\label{httpexample.com} \addcontentsline{toc}{section}{{http://example.com/}}4.2 对照实验一去掉{-}编号 列目录pandoc --tolatex EOF http://example.com/ EOF得到\section{...}无星号且不需要\addcontentsline——因为普通\section本身就会进目录。4.3 对照实验二同时加unlisted不编号 不列目录pandoc --tolatex EOF http://example.com/ {.unnumbered .unlisted} EOF【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考