dalibo/pandocker

pandocker

🐳 一个集成了过滤器、模板、字体和额外工具的pandoc Docker镜像

镜像概述和主要用途

pandocker是一个简化pandoc使用的Docker镜像，内置了多种过滤器、模板、字体及辅助工具，无需在本地系统安装复杂依赖即可实现高质量文档转换。该镜像旨在提供开箱即用的pandoc环境，支持Markdown、LaTeX等格式转换为PDF、EPUB、HTML等多种输出格式。

核心功能和特性

内置模板

提供精选LaTeX和HTML模板，无需额外配置即可生成美观文档：

• eisvogel：适用于计算机科学领域的讲义和练习文档，支持pdflatex和xelatex
• easy templates：HTML模板集合，简化网页格式文档生成

实用过滤器

集成多种pandoc过滤器，扩展文档处理能力：

• 文献管理：pandoc-citeproc（处理参考文献和引用）
• 内容包含：pandoc-include（插入外部Markdown文件）、pandoc-codeblock-include（代码块插入外部文件）
• 格式增强：pandoc-latex-admonition（添加提示框）、pandoc-latex-barcode（生成条形码/QR码）、pandoc-latex-color（文本着色）
• 交叉引用：pandoc-crossref（支持章节、图表等交叉引用）
• 变量替换：pandoc-mustache、pandoc-jinja（文档内变量渲染）

开源字体

包含多种开源字体，确保文档排版美观：

• Deja Vu、Lato、Liberation系列字体
• FontAwesome图标字体
• 完整版（full variant）额外包含Noto字体

额外工具

集成文档处理辅助工具：

• dia：流程图绘制工具
• poppler-utils：PDF内容提取工具集
• rsync：文件同步工具

使用场景和适用范围

• 文档格式转换：Markdown转PDF、EPUB、HTML等多种格式
• 学术写作：利用LaTeX模板和引用过滤器生成符合学术规范的论文
• 技术文档生成：结合代码块过滤器和交叉引用功能，生成包含代码示例的技术手册
• 批量文档处理：通过Docker容器化环境，确保多平台一致的文档输出效果
• 无依赖环境：避免在本地系统安装LaTeX、pandoc及其依赖库

安装与升级

获取镜像

通过以下命令拉取稳定版镜像：

console
docker pull docker.xuanyuan.run/dalibo/pandocker:stable

升级镜像

当有新版本发布时，重新执行上述命令更新镜像：

console
docker pull docker.xuanyuan.run/dalibo/pandocker:stable

使用方法和配置说明

基本使用方法

使用常规pandoc参数运行容器，将本地文件挂载到容器内/pandoc目录：

console
docker run --rm -u $(id -u):$(id -g) -v $(pwd):/pandoc docker.xuanyuan.run/dalibo/pandocker README.md -o README.pdf

核心配置参数说明

高级使用技巧

设置命令别名

通过shell别名将pandocker作为pandoc使用，添加到~/.bashrc或~/.zshrc：

console
alias pandoc="docker run --rm -u $(id -u):$(id -g) -v $(pwd):/pandoc dalibo/pandocker:stable"

使用示例：

console
pandoc README.md -o README.epub  # 直接使用别名调用

管道输入模式

通过管道传递内容（注意：不含图片或外部引用时适用）：

console
cat foo.md | docker run --rm -i dalibo/pandocker -t pdf > foo.pdf

模板使用说明

内置模板列表

• eisvogel：计算机科学领域讲义和练习文档模板，支持pdflatex和xelatex
• easy templates：HTML模板集合，适用于网页格式文档

使用方法

通过--template=模板名参数指定模板：

console
docker run --rm -u $(id -u):$(id -g) -v $(pwd):/pandoc docker.xuanyuan.run/dalibo/pandocker --pdf-engine=xelatex --template=eisvogel foo.md -o foo.pdf

模板特定变量需参考原项目文档：https://github.com/Wandmalfarbe/pandoc-latex-template%E3%80%81https://github.com/ryangrose/easy-pandoc-templates

过滤器使用说明

内置过滤器列表

使用方法

通过--filter=过滤器名参数启用过滤器：

console
docker run --rm -v $(pwd):/pandoc docker.xuanyuan.run/dalibo/pandocker --filter=pandoc-crossref --filter=pandoc-citeproc thesis.md -o thesis.pdf

路径说明

使用pandoc-include、pandoc-codeblock-include等涉及文件引用的过滤器时：

• 默认引用路径为/pandoc（即挂载的当前目录）
• 可通过--workdir=路径参数指定自定义工作目录

字体说明

基础版包含字体

• Deja Vu：通用无衬线字体，支持多语言
• Lato：现代无衬线字体，适合屏幕和印刷
• Liberation：替代Arial、Times New Roman的开源字体
• FontAwesome：图标字体，支持文档内图标插入

完整版额外字体

• Noto：Google推出的多语言字体，支持全球主要语言

支持的镜像标签

镜像标签格式：branch[-parent[-variant]]

注意：其他未列出的标签未经过官方支持，使用时需谨慎。

额外工具使用

容器内置以下辅助工具，可通过修改--entrypoint参数调用：

dia（流程图绘制）

将.dia文件转换为SVG：

console
docker run --rm -v $(pwd):/pandoc --entrypoint dia docker.xuanyuan.run/dalibo/pandocker diagram.dia -e diagram.svg

poppler-utils（PDF工具集）

提取PDF文本内容：

console
docker run --rm -v $(pwd):/pandoc --entrypoint pdftotext docker.xuanyuan.run/dalibo/pandocker document.pdf -

构建镜像

如需自定义构建镜像，可使用以下方法：

console
docker build .  # 直接构建
# 或使用Makefile
make