Wandmalfarbe/pandoc-latex-template · 上手攻略

  • 仓库：Wandmalfarbe/pandoc-latex-template
  • 链接：https://github.com/Wandmalfarbe/pandoc-latex-template
  • 分类：academic-writing（pandoc 模板 / LaTeX）
  • 作者：spark
  • 更新：2026-07-15

是什么

pandoc-latex-template 是 Wandmalfarbe 维护的 pandoc LaTeX 模板（代号 Eisvogel），目标是让你的 Markdown 直接转出"看起来像正式出版物 / 讲义"的 PDF 或 .tex，免去手写 LaTeX 模板的痛苦。

模板自带：

  • 自定义封面页（可指定背景色、字体色、logo、整页背景图）
  • 整本可读的正文页（支持自定义页背景图、页眉页脚、目录、独立分页）
  • 代码块高亮（基于 LaTeX 的 listings 包，也兼容 pygments / kate / tango 等）
  • 彩色 tcolorbox / awesomebox 风格的提示框（tip / warning / note / box 等）
  • 行内图标支持（fontawesome5 / academicons）
  • 双面 / 单面、book / article / Beamer 幻灯片都覆盖

定位是"lecture notes & exercises in CS"，但实际上适合一切要写讲义、培训材料、产品文档、轻量论文的场合。

解决什么问题

  • 想写纯 Markdown，但导出要 LaTeX 级别排版（代码块彩色、封面漂亮、数学公式干净、参考文献齐全）。
  • 不想从零写 LaTeX preamble——Eisvogel 已经替你处理了 hyperref、geometry、listings、tcolorbox、fontawesome、unicode-math 等一坨宏包。
  • 想让讲义、Slide、PDF 三套用同一份 Markdown——Eisvogel 同时出 eisvogel.latex（article）和 eisvogel.beamer（幻灯片）两套模板。
  • 想在公司机器、CI、远程服务器上一键构建 PDF——配合 pandoc/extra Docker 镜像，连 LaTeX 都帮你装好了。

快速安装

当前稳定版：Eisvogel v3.5.0（2026-06-28 发布，2026-07-04 有过补丁 release），要求 pandoc 3.x。

方式一：本地安装（推荐开发机）

# 1) 装 pandoc 和 LaTeX
# macOS:
brew install pandoc
brew install --cask mactex-no-gui   # 或者更小的 basictex
# Debian/Ubuntu:
sudo apt-get install pandoc texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra texlive-latex-recommended

# 2) 下载最新 release 的 ZIP（v3.5.0+）
#    https://github.com/Wandmalfarbe/pandoc-latex-template/releases/latest
unzip eisvogel.zip -d eisvogel

# 3) 把模板放到 pandoc 模板目录（仓库 README 给的几个候选路径任选其一）
mkdir -p ~/.local/share/pandoc/templates
cp eisvogel/eisvogel.latex      ~/.local/share/pandoc/templates/
cp eisvogel/eisvogel.beamer     ~/.local/share/pandoc/templates/
# Windows: %APPDATA%\pandoc\templates\

# 4) 验证
pandoc --version | head -1
ls ~/.local/share/pandoc/templates/

注意：仓库 README 明确说 eisvogel.latex 和 eisvogel.beamer 这两个 standalone 文件不在 Git 仓库里，要使用必须从 release 下载；Git 仓里只有多文件版 template-multi-file/（供开发贡献）。

方式二：Docker（最省心，CI 推荐）

docker pull pandoc/extra:3.5

# 把当前目录挂到容器里，用 Eisvogel 模板输出 PDF
docker run --rm \
  --volume "$(pwd):/data" \
  --user "$(id -u):$(id -g)" \
  pandoc/extra:3.5 \
  example.md -o example.pdf --template eisvogel --syntax-highlighting idiomatic

# 想要 shell 别名
alias pandock='docker run --rm -v "$(pwd):/data" -u "$(id -u):$(id -g)" pandoc/extra:3.5'
pandock example.md -o example.pdf --template eisvogel --syntax-highlighting idiomatic

pandoc/extra 镜像里 pandoc、TeXLive、eisvogel 模板、pandoc-latex-environment filter、开源字体都是全的。

核心用法

1. 最小 Markdown → PDF 命令

pandoc example.md -o example.pdf \
  --from markdown \
  --template eisvogel \
  --syntax-highlighting idiomatic

example.md 顶部放 YAML metadata：

---
title: "深度学习入门"
author: [张三, 李四]
date: "2026-07-15"
keywords: [machine learning, notes]
---

2. 彩色封面页

---
title: "Hands-on MCP"
author: Anan
titlepage: true
titlepage-color: "142850"       # 不要带 #
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "FFFFFF"
titlepage-rule-height: 4
titlepage-logo: "images/logo.pdf"   # 相对执行命令时的路径
---

3. 自定义页眉页脚

---
title: "API Reference"
header-left: "MCP-Agent"
header-right: "v0.4.0"
footer-left: "Anan"
footer-right: "Page \\thepage"
---

或者一次性 -V header-left="..." 也行。

4. 漂亮提示框（依赖 pandoc-latex-environment filter）

注意：Eisvogel 要求 pandoc-latex-environment 这个 filter 来生成彩色 box。用 pandoc/extra 镜像自带；本地装可在 pandoc 之后 pip install pandoc-latex-environment，再 --filter pandoc-latex-environment。

::: warning
这里是警告内容，渲染成橘黄色边框。
:::

::: tip
这里是 tip 提示。
:::

支持的 box：note、tip、warning、caution、important、box、success、failure、question、example、quote、elaborate。

5. 代码块语法高亮

pandoc example.md -o example.pdf \
  --template eisvogel \
  --syntax-highlighting idiomatic   # 用 listings
# 或者：
  --syntax-highlighting pygments
  --syntax-highlighting kate
  --syntax-highlighting tango

idiomatic 出来的风格和模板官方示例 PDF 一致。

6. 出独立 .tex（用自己 LaTeX 编辑器继续排版）

pandoc example.md -o example.tex --template eisvogel

7. 改变语言（影响自动断字）

pandoc example.md -o example.pdf --template eisvogel -V lang=zh-CN
pandoc example.md -o example.pdf --template eisvogel -V lang=de

8. 写成书（book 模式）

pandoc book.md -o book.pdf \
  --template eisvogel \
  -V book \
  --top-level-division=chapter \
  -V classoption=oneside      # 不要隔页空白页（用于 PDF 阅读）

--top-level-division=chapter 让 Markdown 的 # 一级标题被映射成 chapter；章节默认从 1 编号，要改用 -V first-chapter=0。

9. 出 Beamer 幻灯片

pandoc slides.md -o slides.pdf \
  --template eisvogel-beamer \
  --toc

可直接用 --slide-level=2 让 ## 成为分页点。

典型适用场景

  • 计算机系讲义 / 课后习题：原设定场景。Markdown 写笔记，pandoc --template eisvogel 直接出 PDF，省去 LaTeX 排版时间。
  • 培训材料 / 公司 Wiki 文档：HR 招新手册、合规培训、API 文档都能用一份 Markdown 同源出 PDF + HTML。
  • 轻量级论文 / 课程作业 / 毕设初稿：论文级别的分章 / 参考文献 / 数学公式 + 彩色 box + 代码块高亮。
  • 项目交付报告：用 watermark: "DRAFT" 加整页水印，配 titlepage-background 放公司 logo。
  • Slide 自动化生成：内容变化不大的内部培训 Slide，Markdown 写一遍，eisvogel-beamer 模板出一份 PDF。

坑与注意

  1. eisvogel.latex / eisvogel.beamer 不在 Git 主分支：clone 仓库下来直接拷文件会遇到[!IMPORTANT] This file is NOT present in this Git repository and has to be obtained from a released version of the template.。必须去 Releases 页 下载 ZIP。
  2. pandoc ≥ 3.8.2.1 有兼容问题：CHANGELOG 里专门提了一句，\newcounter{none} 引入。修复方式：升级 Eisvogel 到 ≥ v3.4.0 版本（推荐 v3.5.0）。
  3. texlive-full ≈ 5 GB：本地不想装全功能，就装 texlive-latex-extra 然后手动 tlmgr install 缺的包（README 列了一长串：adjustbox / babel-german / background / bidi / collectbox / csquotes / everypage / filehook / footmisc / footnotebackref / framed / fvextra / ...）。
  4. Windows / macOS 提示框不显示：通常是因为缺 pandoc-latex-environment filter 或它在 PATH 上找不到。先 pip install pandoc-latex-environment 看输出。
  5. titlepage-logo 路径：README 特别强调"always relative to where pandoc is executed"，--resource-path 不生效。CI 里跑的话要保证执行目录里能找到 logo。
  6. Book 双面空白页：默认两章之间会有一页空白（twoside），阅读体验像纸书；PDF 版想要更紧凑就 -V classoption=oneside。
  7. CJK 中文：lang=zh-CN 是基础，xelatex / lualatex 才能正确处理中文，需要 texlive-lang-chinese 包；或者改用 pandoc/extra 镜像（已经带齐）。
  8. 没有官方 Quarto / Typst 桥接：模板只服务 pandoc 路径。如果用 Typst 走现代排版路线，请看其他项目。

与同类对比

模板 / 工具 美观度 易用 维护活跃度 适合
Eisvogel 高（最美那一档） 高（YAML 全控制） 高（v3.5 / 2026-06） 讲义 / 报告 / 简单 book
pandoc 默认 LaTeX 一般 极高 跟着 pandoc 走 极简纯学术
Tufte Handout 中（保留页边笔记） 中 中 单边笔记风格讲义
LaTeX Pandoc template by Dapper 中 中 中 book / 长篇
Typst（@preview/elegant-*） 高 极高 高（2025 后加速） 想离开 LaTeX
md-to-pdf（MPE / weasyprint） 一般 高 中 HTML 风格 PDF

核心差异：Eisvogel 是 pandoc 生态里最像生产成品的 LaTeX 模板，且支持 box / 背景图 / watermark 等"开箱可用"的装饰元素，是 Markdown 圈出"像样 PDF"的最短路径。

一句话推荐结论

你已经习惯 Markdown，又想要一份能发给老板 / 学生 / 客户的"漂亮 PDF"——pandoc-latex-template（Eisvogel）+ pandoc/extra Docker 是门槛最低的组合，5 分钟能跑出一份 PDF。

来源

  • 仓库 README：https://github.com/Wandmalfarbe/pandoc-latex-template
  • Releases / 最新版本：https://github.com/Wandmalfarbe/pandoc-latex-template/releases/latest（v3.5.0, 2026-06-28；2026-07-04 仍有 patch release）
  • Eisvogel 独立目录：https://pandoc-templates.org/template/eisvogel
  • pandoc 官方：https://pandoc.org/
  • Docker 镜像：https://hub.docker.com/r/pandoc/extra
  • 例程：examples/basic-example/document.md 等在仓库 examples/ 下

不确定处

  • Eisvogel v3.5.0 之后的下一个 minor 号（如 3.5.x / 3.6.0）发版节奏未在仓库 README 公开，预计按 CHANGELOG 节奏继续。
  • Mactex / basictex 在 Apple Silicon 上字体问题的旧 issue 在 v3.5 是否完全解决未单独核对。
  • pandoc-latex-environment filter 与最新 pandoc 3.x 的兼容性未单独测矩阵，按 README 看 v3.4+ 已经修过 pandoc 3.8.2.1 的 \newcounter{none} 问题。