Epilogue {.standout}

原创2026-09-20 22:48:311,336 阅读
文章标签:文档CLI开发工具模板引擎插件系统富文本WebAssembly

Epilogue {.standout}


`{.standout}` 是 pandoc 的 heading 属性(attribute)语法,这里的 `standout` 是 class。期望输出将其转换成了:

```latex
\begin{frame}[standout]{Epilogue}

即 class 被透传为 frame 环境的可选参数。这在源码中有清晰依据:src/Text/Pandoc/Writers/LaTeX.hs 中,writer 将 frame 的 div class 与 heading class 合并,再与 frameoptions 白名单比对:

let frameoptions = ["allowdisplaybreaks", "allowframebreaks", "fragile",
                    "b", "c", "t", "environment", "s", "squeeze",
                    "label", "plain", "shrink", "standout",
                    "noframenumbering", "containsverbatim"]
...
[k | k <- classes, k `elem` frameoptions] ++

任何命中白名单的 class 都会被写进 \begin{frame}<a href="https://link.gitcode.com/i/54822ee760222f0f67a8dd296438fc8f" target="_blank">...] 的方括号选项中。standout 正是 Beamer 主题(如 Madrid、metropolis)中用于"收尾强调帧"的经典选项,[MANUAL.txt 也确认了这一点:

All of the other frame attributes described in Section 8.1 of the Beamer User's Guide may also be used: allowdisplaybreaks, allowframebreaks, b, c, s, t, environment, label, plain, shrink, standout, noframenumbering, squeeze.

可用的完整帧选项清单(取自上述源码白名单)如下:

class / 属性 生成的帧选项 典型用途
{.fragile} [fragile] 帧内含有 verbatim/代码(如 minted)
{.allowframebreaks} [allowframebreaks] 内容溢出时自动拆成多帧(常用于参考文献)
{.standout} [standout] 主题强调帧(收尾帧)
{.plain} [plain] 无标题栏/边栏的纯帧
{.shrink} [shrink] 内容自动缩小以适配帧
{.squeeze} [squeeze] 压缩帧内垂直间距
{.b} / {.c} / {.t} / {.s} [b] / [c] / [t] / [s] 帧内内容垂直对齐
{.noframenumbering} [noframenumbering] 不在帧上显示帧号
{frameoptions="..."} 原样透传 传递任意自定义帧选项

其中 frameoptions 属性允许绕过白名单,把任意字符串原样塞进帧选项(src/Text/Pandoc/Writers/LaTeX.hs):

# Heading {frameoptions="squeeze,shrink,customoption=foobar"}

另外值得注意:fragile 除了手动声明,还会被自动推导——只要帧内检测到代码块或行内代码,writer 会自动加上 <a href="https://link.gitcode.com/i/524092a9437f39cbee8d5fe2ffc98414" target="_blank">fragile]([src/Text/Pandoc/Writers/LaTeX.hs)。

自动标签:\label 与 \phantomsection

期望输出中每一处标题都伴生了标签:

\section{A circus!}\label{a-circus}
\begin{frame}{Another silly title}
\protect\phantomsection\label{another-silly-title}
\begin{frame}[standout]{Epilogue}
\protect\phantomsection\label{epilogue}

机制如下:

  • 标题文本 "A circus!" 经 pandoc 的 slug 化处理得到标识符 a-circus;section 命令后直接输出 \label{a-circus};
  • 帧标题内的标签不是直接 \label,而是 \protect\phantomsection\label{another-silly-title}。这是因为在帧(frame 环境)内部放置 \label 时,为了让交叉引用指向正确位置,需要先用 \phantomsection 占位。

源码依据在 src/Text/Pandoc/Writers/LaTeX/Util.hs 的 hypertarget 函数:

hypertarget "" = return mempty
hypertarget ident = do
  inHeading <- gets stInHeading
  if inHeading
     then do
      ref <- literal <$> toLabel ident
      return $ text "\\protect\\hypertarget" <> braces ref <> "{}"
     else do
      label <- labelFor ident
      return $ text "\\protect\\phantomsection" <> label

当处于标题(heading)内部时使用 \protect\hypertarget{...}{},否则使用 \protect\phantomsection\label{...}。而 \section、\begin{frame} 处的标签生成分别位于 src/Text/Pandoc/Writers/LaTeX.hs(帧的 slideAnchor)等位置。

标签本身由标题文本 slug 化而来:pandoc 会把 "Another silly title" 转成 another-silly-title,把 "Epilogue" 转成 epilogue。这意味着即便不手动写 {#id},每个标题也会获得一个可被 \ref/\hyperref 引用的稳定标签;若标题带显式标识符(如 ## Epilogue {#end}),则会优先使用该标识符。

综合实战:复现并扩展这条用例

复现原始输出

在仓库根目录执行:

pandoc -t beamer <<'EOF'
---
title: A silly slide
subtitle: Look for the sequel!
---

# A circus!

## Another silly title

Not much to do about nothing.

## Epilogue {.standout}
EOF

输出应与测试期望完全一致(含 \section{A circus!}\label{a-circus}、两个 frame、[standout] 选项及两处 \phantomsection\label)。若想进一步编译为 PDF,需本地安装 TeX Live 且包含 beamer 宏包:

pandoc slides.md -t beamer -o slides.pdf

面向实战的扩展示例

在原始用例基础上,加入参考文献帧、代码帧与手动标签,验证前面讨论的机制:

---
title: A silly slide
subtitle: Look for the sequel!
---

# A circus!

## Another silly title

Not much to do about nothing.

## Epilogue {.standout}

# Back matter

## References {.allowframebreaks}

- Knuth, *The TeXbook*.
- Lamport, *LaTeX: A Document Preparation System*.

## Code sample {#code-sample .fragile}

```haskell
main :: IO ()
main = putStrLn "hello"
登录后查看全文
pandoc