pandoc-pdf-generation

Pandoc PDF 生成

自我演进的技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

概述

使用 Pandoc 和 XeLaTeX 引擎将 Markdown 生成为专业的 PDF 文档。此技能涵盖自动章节编号、目录、参考文献管理、LaTeX 自定义，以及通过实际生产使用总结出的常见故障排查模式。

何时使用此技能

在以下情况下使用此技能：

• 需要按照专业格式要求将 Markdown 转换为 PDF
• 需要自动章节编号和目录
• 需要管理引文和参考文献，避免手动重复
• 需要控制 LaTeX 输出中的表格格式和分页
• 需要构建自动化 PDF 生成工作流

快速入门：通用构建脚本

单一事实来源模式

此技能在 $(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/ 中提供经过生产验证的资源：

• table-spacing-template.tex - 经过生产调优的 LaTeX 导言区（booktabs、colortbl、目录修复）
• build-pdf.sh - 通用自动检测构建脚本

在任意项目中使用

/usr/bin/env bash << 'DETECT_EOF'
# Create symlink once per project (git-friendly)
ln -s "$(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/build-pdf.sh" build-pdf.sh

# Auto-detect single .md file in directory (landscape default)
./build-pdf.sh

# Portrait mode
./build-pdf.sh --portrait document.md

# Monospace font for ASCII diagrams
./build-pdf.sh --monospace diagrams.md

# Explicit input/output
./build-pdf.sh input.md output.pdf
DETECT_EOF

选项：

功能：

• ✅ 自动检测输入文件（如果只有一个 .md 文件）
• ✅ 自动检测参考文献文件（references.bib）和 CSL 文件
• ✅ 始终使用此技能中经过生产验证的 LaTeX 导言区
• ✅ 构建前检查（pandoc、xelatex、文件是否存在）
• ✅ 构建后验证（文件大小、页数）
• ✅ 代码块保持在同一页，不会跨页拆分
• ✅ 使用 Lua 过滤器在 PDF 输出中隐藏 <details> 块

横向 PDF（快速命令）

生成带蓝色超链接的横向 PDF（不依赖 build-pdf.sh）：

pandoc file.md -o file.pdf \
  --pdf-engine=xelatex \
  -V geometry:a4paper,landscape \
  -V geometry:margin=1in \
  -V fontsize=11pt \
  -V mainfont="DejaVu Sans" \
  -V colorlinks=true \
  -V linkcolor=blue \
  -V urlcolor=blue \
  --toc --toc-depth=2 \
  --number-sections

适合横向排版的场景：宽数据表、对比矩阵、包含代码块的技术文档。

手动命令（带 LaTeX 导言区）

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
pandoc document.md \
  -o document.pdf \
  --pdf-engine=xelatex \
  --toc \
  --toc-depth=3 \
  --number-sections \
  -V geometry:margin=1in \
  -V mainfont="DejaVu Sans" \
  -H "$(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/table-spacing-template.tex"
SKILL_SCRIPT_EOF

ASCII 图表

ASCII 图表需要保持字符对齐一致，才能在 PDF 渲染后维持原样：请统一使用制表字符，并确保每一行的宽度相同。

同样重要：请将注释放在代码块之外。不要在图表代码块内添加类似 # contains: file1, file2 的行内注释，否则会破坏对齐。

隐藏 PDF 输出中的内容

使用 --hide-details 从 PDF 输出中移除 <details> 块。适用于以下情况：

• 图表源代码块：将源代码保留在 Markdown 中以便重新生成图表，但在打印版 PDF 中隐藏
• 技术实现说明：在网页或 Markdown 视图中显示，在打印讲义中隐藏
• 可折叠章节：HTML <details> 标签在 PDF 中不会呈现为可折叠内容

用法：

./build-pdf.sh --hide-details document.md

Markdown 模式：

## My Section

```diagram
┌─────┐     ┌─────┐
│ Box │ ──> │ Box │
└─────┘     └─────┘
```

[Box] -> [Box]

With --hide-details, the entire <details> block is stripped from PDF output while remaining visible in markdown/HTML.

Verification Checklist

Before considering a PDF "done", verify:

Pre-Generation:

• No manual section numbering in markdown (use --number-sections)
• Annotations are outside code blocks, not inside

Post-Generation:

• Open PDF and visually inspect each page
• Verify diagrams don't break across pages
• Check section numbering is correct (no "1. 1. Title" duplication)
• Confirm bullet lists render as bullets, not inline dashes

Pre-Print:

• Get user approval before printing
• Confirm orientation preference (landscape/portrait)
• Confirm duplex preference (one-sided/two-sided)

Printing Workflow

Always let the user review the PDF before printing.

Open for review:

open output.pdf

单面打印：

lpr -P "PRINTER_NAME" -o Duplex=None output.pdf

双面打印：

lpr -P "PRINTER_NAME" -o Duplex=DuplexNoTumble output.pdf  # Long-edge binding
lpr -P "PRINTER_NAME" -o Duplex=DuplexTumble output.pdf    # Short-edge binding

查找打印机名称：

lpstat -p -d

未经用户批准，切勿打印——如果存在问题，这会浪费纸张。

参考文档

如需详细信息，请参阅：

• 核心开发原则 - 从这里开始 - 从生产环境故障中总结出的通用原则
• 用于 PDF 的 Markdown - 用于生成整洁横向 PDF 的 Markdown 结构模式
• YAML Front Matter 结构 - YAML 元数据模式
• LaTeX 自定义 - 导言区和表格格式
• 参考文献与引用 - BibTeX 和 CSL 样式
• 文档模式 - 文档类型模板
• 故障排查 - 常见问题及解决方法

故障排查

执行后复盘

此技能完成后，请在结束前检查：

1. 命令是否执行成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否有变化？ — 如果底层工具的接口发生变化，请相应更新 Usage 示例和 Parameters 表。
3. 是否需要变通方案？ — 如果你不得不临时调整（使用不同的标志、增加步骤），请更新此 SKILL.md，避免下次调用时再次需要相同的变通方案。

仅当问题确实存在且可复现时才进行更新，不要基于猜测更新。