pandoc-latex-template 实现单页横向布局：pdflscape 与 pandoc-latex-environment 实战

• 文档

导读

在文档排版中，宽图、宽表等元素在纵向（portrait）页面里往往放不下或严重压缩可读性，此时最优雅的解决方案是让单个页面切换为横向（landscape）排版，而文档其余页面保持纵向。本文以 Eisvogel（pandoc-latex-template 项目）仓库中的 landscape-pdflscape 示例 为主线，完整讲解如何借助pandoc-latex-environment过滤器与 LaTeX 的pdflscape包，在 Markdown 中通过简单的::: landscape分隔符标记，一键生成"整页横向 + 其余纵向"的混合排版 PDF。读完本文你将掌握：YAML 前置元数据的正确写法、过滤器的安装与调用方式、模板注入 LaTeX 包的底层机制，以及它与lscape、KOMA-Scriptpaper=landscape两种方案的差异与取舍。

一、为什么需要"单页横向"排版

大多数文档（论文、报告、讲义）采用纵向页面，这是阅读的主流形态。但以下内容在纵向页面中体验很差：

• 宽幅图片：横向构图的大图缩放到纵向页宽后细节尽失；
• 宽表格：列数多的表格被挤压到无法辨认；
• 时序图、架构图、数据大屏截图：宽度远大于高度。

传统的整文档横向方案（把全文都设为横向）会破坏整体阅读节奏，因此更实用的做法是按需切换：文档默认纵向，仅对包含大图/大表的特定页面启用横向。"整页横向"意味着不仅页面内容旋转，连纸张本身也横向（即页面的宽高比交换），这样才能获得真正的可用宽度。

二、核心配置解析：YAML 前置元数据

landscape-pdflscape 示例 的完整 YAML 元数据块如下：

--- title: "Landscape with pandoc-latex-environment and pdflscape" author: [Pascal Wagler] date: "2025-11-29" subject: "Markdown" keywords: [Markdown, Example] lang: "en" colorlinks: true header-includes: - | ```{=latex} \usepackage{pdflscape}

pandoc-latex-environment: landscape: [landscape] ...

其中有两个关键配置项，缺一不可： ### 1. `header-includes`：把 LaTeX 包注入文档头部 `header-includes` 是 pandoc 标准的元数据变量，用于在生成的 LaTeX 文档序言（preamble）中追加任意 LaTeX 代码。这里通过 pandoc 的"raw LaTeX 内联"语法： ```yaml header-includes: - | ```{=latex} \usepackage{pdflscape}

向文档导入了 `pdflscape` 宏包。该包由 CTAN 的 lscape 生态提供，核心能力是提供 `landscape` 环境：环境内的页面会被横向排版，同时页面本身的纸张方向随之翻转（配合 pdflscape 的 `\pdfpagesattr` 机制，PDF 阅读器也会把该页识别为横向）。 > 注意 `header-includes` 的值是一个**列表**，每一项可以是一条带 `{=latex}` 标记的代码块，这保证了 pandoc 不会解析其中的内容，而是原样写入 LaTeX 输出。 ### 2. `pandoc-latex-environment`：建立 Markdown div 与 LaTeX 环境的映射 ```yaml pandoc-latex-environment: landscape: [landscape]

这是pandoc-latex-environment过滤器的配置：声明一个名为landscape的自定义环境，并将其映射到 Markdown 的::: landscape分隔符（fenced div）。映射关系是"环境名 → div 类名列表"，此处意为：所有带有landscape类的 div 都会被翻译成\begin{landscape} ... \end{landscape}。

3.classoption的对照：模板如何透传纸张选项

如果选择整文档横向，则不需要过滤器，只需在 YAML 中声明classoption，例如 landscape-koma-script 示例 中的写法：

classoption: paper=landscape

在 Eisvogel 模板中，classoption会被原样透传给\documentclass。从 template-multi-file/eisvogel.latex 的源码可以看到这一机制：

$for(classoption)$ $classoption$$sep$, $endfor$

Eisvogel 基于 KOMA-Script 的scrartcl/scrbook文档类（见同一文件第 63 行的\documentclass[...]{$if(book)$scrbook$else$scrartcl$endif$}），因此paper=landscape会作为 KOMA-Script 类选项生效，实现全文横向。

三、正文中如何使用：::: landscape分隔符

配置完成后，正文中的用法非常简洁。示例文档 landscape-pdflscape/document.md 展示了声明与真实使用两个部分：

语法示意：

::: landscape This page will be in landscape format. It is usually used for large images or tables. [![Nam liber tempor cum soluta nobis mazim placerat facer.](https://raw.gitcode.com/gh_mirrors/pa/pandoc-latex-template/raw/68bcbbb292c506bef169a5aa1dced9bbbd6a8cbc/examples/landscape-pdflscape/image.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/9eae424ca684a52aac623d1666f4c433) :::

示例文档中的实际内容（Markdown 渲染后立即生效）：

::: landscape This page will be in landscape format. It is usually used for large images or tables. [![Nam liber tempor cum soluta nobis mazim placerat facer.](https://raw.gitcode.com/gh_mirrors/pa/pandoc-latex-template/raw/68bcbbb292c506bef169a5aa1dced9bbbd6a8cbc/examples/landscape-pdflscape/image.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/9eae424ca684a52aac623d1666f4c433) :::

要点说明：

• ::: landscape开启环境，:::单独成行关闭环境；
• 环境内部是完整的 Markdown 内容，图片、表格、段落、列表均可正常渲染，因为 pandoc 仍会先将其解析为 AST，再由过滤器包进 LaTeX 环境；
• [![图片描述](https://raw.gitcode.com/gh_mirrors/pa/pandoc-latex-template/raw/68bcbbb292c506bef169a5aa1dced9bbbd6a8cbc/examples/landscape-pdflscape/image.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/9eae424ca684a52aac623d1666f4c433)中的描述文本会成为 LaTeX 图片标题（caption）；
• 横向页面内部的内容排版宽度会自动适配横向纸张，宽图无需再做缩放处理。

四、完整构建命令与前置条件

仓库中每个示例目录都附带了build.sh，landscape-pdflscape/build.sh 中的完整命令为：

pandoc "document.md" -o "document.pdf" --from markdown --template "../../dist/eisvogel.latex" --filter pandoc-latex-environment --syntax-highlighting idiomatic

逐段拆解这条命令：

过滤器安装说明

pandoc-latex-environment是 pandoc 生态的外部过滤器，需要通过包管理器安装，例如：

# Lua 版本（pandoc 3 推荐） luarocks install pandoc-latex-environment # 或通过 pip 安装 Python 版本 pip install pandoc-latex-environment

安装后确保pandoc-latex-environment可执行文件在 PATH 中，pandoc 通过--filter调用它。若省略--filter参数，::: landscape分隔符会被 pandoc 当作普通 div 处理，\usepackage{pdflscape}虽已注入但不会产生任何横向效果——这一点是排错时的首要检查项。

依赖的 LaTeX 包

pdflscape属于较常见的 LaTeX 宏包。若使用精简版 TeX Live 而缺少该包，可单独安装：

tlmgr install pdflscape

在 Debian/Ubuntu 系可直接apt-get install texlive-latex-extra（README 的 Required LaTeX Packages 一节列出了 Eisvogel 的完整包依赖清单，texlive-latex-extra是覆盖常用包的最小推荐集合）。

五、底层原理：模板如何注入header-includes

header-includes之所以能生效，是因为 Eisvogel 模板在序言中预留了注入点。查看 template-multi-file/eisvogel.latex：

$for(header-includes)$ $header-includes$ $endfor$ $after-header-includes.latex()$

• $for(header-includes)$遍历 YAML 中header-includes列表的每一项，按顺序写入 LaTeX 序言；
• 紧随其后的$after-header-includes.latex()$是 Eisvogel 预留的扩展钩子，可在 template-multi-file/after-header-includes.latex 中追加模板级代码。

因此，\usepackage{pdflscape}会出现在\begin{document}之前，宏包定义的环境对全文可见。同样的注入机制也适用于其他示例（例如 boxes-with-pandoc-latex-environment-and-tcolorbox/document.md 用header-includes定义自定义盒子环境），这是 Eisvogel 扩展性的重要体现。

pandoc-latex-environment 过滤器的作用阶段

从 pandoc 的转换流程看：pandoc 先将 Markdown 解析为 AST（其中::: landscape是带类的 Div 节点），--filter pandoc-latex-environment在 AST 阶段遍历所有 Div，凡类名命中pandoc-latex-environment映射表中声明的环境名，就把该 Div 改写为 LaTeX 环境（raw block），最后由 Eisvogel 模板渲染成\begin{landscape}...\end{landscape}。这也解释了为什么环境内部可以自由使用 Markdown 语法——AST 中的内联元素会在环境内按正常规则序列化。

六、三种横向方案对比与选型

仓库中同时收录了三个横向相关示例，恰好覆盖三种不同的横向需求，对比选择如下：

三者取舍要点：

• 若目标是屏幕阅读 + 宽内容展示，pdflscape是最佳选择：它调用 PDF 底层机制（\pdfpagesattr）让阅读器将单页识别为横向，缩放、翻页体验最自然；
• 若目标是打印，lscape通过\rotatebox旋转内容更可靠，因为纸张保持纵向，双面打印时页序与装订方向不被打乱；
• 若整个文档（如幻灯片、大幅图表册）都需要横向，直接用classoption: paper=landscape最省事，且无需安装任何过滤器。

从配置上看，lscape与pdflscape的差异仅在于header-includes中导入的包名（\usepackage{lscape}vs\usepackage{pdflscape}），正文的::: landscape写法完全一致，切换成本极低。

七、常见问题与排错指南

结合源码与示例，整理如下易错点：

1. 忘记--filter pandoc-latex-environment症状：PDF 生成成功，但内容仍是纵向排版。检查构建命令（参考 build.sh）是否包含该过滤参数。

2. YAML 缩进错误header-includes列表项必须正确缩进，{=latex}代码块语法不能写错，否则 pandoc 会把它当作普通文本段落输出到 PDF 中。

3. 包缺失报错若编译报File 'pdflscape.sty' not found，按上文tlmgr install pdflscape或安装texlive-latex-extra解决。

4. 横向页内图片仍过宽横向页面本身已提供更宽的可排区域，但若图片源文件分辨率过低，放大后仍会模糊，建议使用高分辨率图片并配合 Markdown 的宽度语法（如[![caption](https://raw.gitcode.com/gh_mirrors/pa/pandoc-latex-template/raw/68bcbbb292c506bef169a5aa1dced9bbbd6a8cbc/examples/landscape-pdflscape/image.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/9eae424ca684a52aac623d1666f4c433){width=...}）控制显示尺寸。

5. 环境未闭合::: landscape必须以独立成行的:::结束，未闭合的 div 会导致过滤器和 LaTeX 双双报错。

八、小结

通过 landscape-pdflscape 示例 可以看到，Eisvogel 模板 +pandoc-latex-environment过滤器 +pdflscape宏包三者配合，可以把"单页横向"这种原本需要手写大量 LaTeX 的操作，压缩成 Markdown 中一对::: landscape分隔符。核心要点可归纳为三步：

1. 在 YAML 的header-includes中通过{=latex}导入\usepackage{pdflscape}；
2. 在 YAML 的pandoc-latex-environment中声明landscape: [landscape]映射；
3. 构建时携带--filter pandoc-latex-environment，正文中即可用::: landscape包裹宽图或宽表。

该模式同样适用于仓库中的 landscape-lscape（打印场景）与 landscape-koma-script（全文横向）两种变体，读者可按实际需求在三种方案间灵活切换。

• 文档