pandoc-pdf-generation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pandoc PDF Generation

Pandoc PDF 生成

Overview

概述

Generate professional PDF documents from Markdown using Pandoc with the XeLaTeX engine. This skill covers automatic section numbering, table of contents, bibliography management, LaTeX customization, and common troubleshooting patterns learned through production use.

使用搭配XeLaTeX引擎的Pandoc，从Markdown生成专业的PDF文档。本技能涵盖自动章节编号、目录、参考文献管理、LaTeX自定义，以及从生产实践中总结的常见故障排查方案。

When to Use This Skill

适用场景

Use this skill when:

Converting Markdown to PDF with professional formatting requirements
Needing automatic section numbering and table of contents
Managing citations and bibliographies without manual duplication
Controlling table formatting and page breaks in LaTeX output
Building automated PDF generation workflows

在以下场景中使用本技能：

需要将Markdown转换为具备专业格式要求的PDF
需自动生成章节编号和目录
无需手动重复操作即可管理引用和参考文献
控制LaTeX输出中的表格格式和分页
构建自动化PDF生成工作流

Quick Start: Universal Build Script

快速开始：通用构建脚本

Single Source of Truth Pattern

单一事实源模式

This skill provides production-proven assets in

${CLAUDE_PLUGIN_ROOT}/skills/pandoc-pdf-generation/assets/

```
table-spacing-template.tex
```
- Production-tuned LaTeX preamble (booktabs, colortbl, ToC fixes)
```
build-pdf.sh
```
- Universal auto-detecting build script

本技能在

${CLAUDE_PLUGIN_ROOT}/skills/pandoc-pdf-generation/assets/

路径下提供经过生产验证的资源：

```
table-spacing-template.tex
```
- 经过生产调优的LaTeX前置代码（包含booktabs、colortbl、目录修复）
```
build-pdf.sh
```
- 通用自动检测构建脚本

From Any Project

任意项目中使用

bash

/usr/bin/env bash << 'DETECT_EOF'

bash

/usr/bin/env bash << 'DETECT_EOF'

Create symlink once per project (git-friendly)

每个项目创建一次符号链接（兼容git）

ln -s ${CLAUDE_PLUGIN_ROOT}/skills/pandoc-pdf-generation/assets/build-pdf.sh build-pdf.sh

Auto-detect single .md file in directory (landscape default)

自动检测目录中的单个.md文件（默认横向模式）

./build-pdf.sh

Portrait mode

纵向模式

./build-pdf.sh --portrait document.md

Monospace font for ASCII diagrams

等宽字体适配ASCII图

./build-pdf.sh --monospace diagrams.md

Explicit input/output

显式指定输入/输出

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


**Options:**

| Flag             | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `--landscape`    | Landscape orientation (default)                            |
| `--portrait`     | Portrait orientation                                       |
| `--monospace`    | Use DejaVu Sans Mono - ideal for ASCII diagrams            |
| `--hide-details` | Hide `<details>` blocks (e.g., graph-easy source) from PDF |
| `-h, --help`     | Show help message                                          |

**Features:**

- ✅ Auto-detects input file (if single .md exists)
- ✅ Auto-detects bibliography (`references.bib`) and CSL files
- ✅ Always uses production-proven LaTeX preamble from skill
- ✅ Pre-flight checks (pandoc, xelatex, files exist)
- ✅ Post-build validation (file size, page count)
- ✅ Code blocks stay on same page (no splitting across pages)
- ✅ Lua filter to hide `<details>` blocks from PDF output

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


**选项说明：**

| 参数             | 描述                                                |
| ---------------- | ---------------------------------------------------------- |
| `--landscape`    | 横向排版（默认）                            |
| `--portrait`     | 纵向排版                                       |
| `--monospace`    | 使用DejaVu Sans Mono字体 - 适配ASCII图            |
| `--hide-details` | 隐藏PDF中的`<details>`块（例如graph-easy源代码） |
| `-h, --help`     | 显示帮助信息                                          |

**功能特性：**

- ✅ 自动检测输入文件（当目录中仅有单个.md文件时）
- ✅ 自动检测参考文献文件(`references.bib`)和CSL文件
- ✅ 始终使用技能中经过生产验证的LaTeX前置代码
- ✅ 预生成检查（pandoc、xelatex、文件存在性）
- ✅ 生成后验证（文件大小、页数）
- ✅ 代码块保持在同一页面（不会跨页拆分）
- ✅ 通过Lua过滤器从PDF输出中隐藏`<details>`块

Landscape PDF (Quick Command)

横向PDF（快速命令）

For landscape PDFs with blue hyperlinks (no build-pdf.sh dependency):

bash

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

Use landscape for: Wide data tables, comparison matrices, technical docs with code blocks.

无需依赖build-pdf.sh，生成带蓝色超链接的横向PDF：

bash

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

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

Manual Command (With LaTeX Preamble)

手动命令（搭配LaTeX前置代码）

bash

/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 ${CLAUDE_PLUGIN_ROOT}/skills/pandoc-pdf-generation/assets/table-spacing-template.tex
SKILL_SCRIPT_EOF

bash

/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 ${CLAUDE_PLUGIN_ROOT}/skills/pandoc-pdf-generation/assets/table-spacing-template.tex
SKILL_SCRIPT_EOF

ASCII Diagrams: Always Use graph-easy

ASCII图：务必使用graph-easy

CRITICAL: Never manually type ASCII diagrams. Always use the

itp:graph-easy

skill.

Manual ASCII art causes alignment issues in PDFs. The graph-easy skill ensures:

Proper boxart character alignment
Consistent spacing
Reproducible output

bash

undefined

重要提示：切勿手动编写ASCII图，始终使用

itp:graph-easy

技能。

手动编写的ASCII图会在PDF中出现对齐问题。graph-easy技能可确保：

正确的框线字符对齐
统一的间距
可重现的输出

bash

undefined

Invoke the skill for general diagrams

调用技能生成通用图表

Skill(itp:graph-easy)

For ADR architecture diagrams

生成ADR架构图

Skill(itp:adr-graph-easy-architect)


**Also important**: Keep annotations OUTSIDE code blocks. Don't add inline comments like `# contains: file1, file2` inside diagram code blocks - they break alignment.

---

Skill(itp:adr-graph-easy-architect)


**另一个注意事项**：注释内容请放在代码块外部。不要在图表代码块内添加类似`# contains: file1, file2`的行内注释，这会破坏对齐效果。

---

Hiding Content for PDF Output

隐藏PDF输出中的内容

Use

--hide-details

to remove

<details>

blocks from PDF output. This is useful when:

graph-easy source blocks: Keep source in markdown for diagram regeneration, but hide from printed PDFs
Technical implementation notes: Show in web/markdown view, hide from printed handouts
Collapsible sections: HTML
```
<details>
```
tags don't render as collapsible in PDF

Usage:

bash

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

Markdown pattern:

markdown

undefined

使用

--hide-details

参数从PDF输出中移除

<details>

块。适用于以下场景：

graph-easy源代码块：在Markdown中保留源代码以便重新生成图表，但在打印PDF中隐藏
技术实现说明：在网页/Markdown视图中显示，在打印讲义中隐藏
可折叠章节：HTML的
```
<details>
```
标签在PDF中无法渲染为可折叠效果

使用方式：

bash

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

Markdown示例：

markdown

undefined

My Section

我的章节

diagram

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


<details>
<summary>graph-easy source</summary>

```
[Box] -> [Box]
```

</details>
```

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

---

diagram

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


<details>
<summary>graph-easy源代码</summary>

```
[Box] -> [Box]
```

</details>
```

使用`--hide-details`参数后，整个`<details>`块会从PDF输出中被移除，但在Markdown/HTML视图中仍可见。

---

Verification Checklist

验证检查清单

Before considering a PDF "done", verify:

Pre-Generation:

No manual section numbering in markdown (use
```
--number-sections
```
)
All ASCII diagrams generated via
```
itp:graph-easy
```
skill
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)

在确认PDF完成前，请验证以下内容：

生成前：

Markdown中无手动章节编号（使用
```
--number-sections
```
参数）
所有ASCII图均通过
```
itp:graph-easy
```
技能生成
注释内容位于代码块外部，而非内部

生成后：

打开PDF并逐页视觉检查
验证图表未跨页拆分
检查章节编号正确（无“1. 1. 标题”这类重复编号）
确认项目符号列表渲染为圆点，而非连字符

打印前：

打印前获得用户确认
确认排版偏好（横向/纵向）
确认双面打印偏好（单面/双面）

Printing Workflow

打印工作流

Always let the user review the PDF before printing.

Open for review:

bash

open output.pdf

Print one-sided (simplex):

bash

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

Print two-sided (duplex):

bash

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

Find printer name:

bash

lpstat -p -d

Never print without user approval - this wastes paper if issues exist.

打印前务必让用户先审阅PDF。

打开PDF供审阅：

bash

open output.pdf

单面打印：

bash

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

双面打印：

bash

lpr -P "PRINTER_NAME" -o Duplex=DuplexNoTumble output.pdf  # 长边装订
lpr -P "PRINTER_NAME" -o Duplex=DuplexTumble output.pdf    # 短边装订

查找打印机名称：

bash

lpstat -p -d

切勿未经用户确认就打印 - 若存在问题会造成纸张浪费。

Reference Documentation

参考文档

For detailed information, see:

Core Development Principles - START HERE - Universal principles learned from production failures
Markdown for PDF - Markdown structure patterns for clean landscape PDFs
YAML Front Matter Structure - YAML metadata patterns
LaTeX Customization - Preamble and table formatting
Bibliography & Citations - BibTeX and CSL styles
Document Patterns - Document type templates
Troubleshooting - Common issues and fixes

如需详细信息，请查看：

核心开发原则 - 从这里开始 - 从生产故障中总结的通用原则
Markdown转PDF - 适用于清晰横向PDF的Markdown结构规范
YAML前置元数据结构 - YAML元数据规范
LaTeX自定义 - 前置代码和表格格式
参考文献与引用 - BibTeX和CSL样式
文档模板 - 不同文档类型的模板
故障排查 - 常见问题与解决方案

Troubleshooting

故障排查

Issue	Cause	Solution
Font not found	DejaVu Sans not installed	`brew install font-dejavu`
xelatex not found	MacTeX not installed	`brew install --cask mactex`
Table breaks across pages	Missing longtable package	Include table-spacing-template.tex preamble
Double section numbers	Manual numbering in markdown	Remove manual numbers, use --number-sections only
ASCII diagram misaligned	Manual ASCII art	Use graph-easy skill for all diagrams
Bullet list renders as dashes	Markdown formatting issue	Check for proper blank lines before lists
Bibliography not rendering	Missing references.bib	Create .bib file or remove --bibliography flag
PDF file size too large	Embedded fonts	Use --pdf-engine-opt=-dEmbedAllFonts=false

问题	原因	解决方案
字体未找到	未安装DejaVu Sans字体	执行 `brew install font-dejavu`
xelatex未找到	未安装MacTeX	执行 `brew install --cask mactex`
表格跨页拆分	缺少longtable包	引入table-spacing-template.tex前置代码
章节编号重复	Markdown中存在手动编号	移除手动编号，仅使用--number-sections参数
ASCII图对齐错误	手动编写ASCII图	所有图表均使用graph-easy技能生成
项目符号列表渲染为连字符	Markdown格式问题	检查列表前是否有正确的空行
参考文献未渲染	缺少references.bib文件	创建.bib文件或移除--bibliography参数
PDF文件过大	嵌入了字体	使用参数--pdf-engine-opt=-dEmbedAllFonts=false