SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场pandoc-pdf-generation

pandoc-pdf-generation

办公与效率

查看项目

更新于 10-15 13:37

技能介绍

用途

Pandoc PDF Generation 用于将 Markdown 文档转换为具有专业排版效果的 PDF。它基于 Pandoc 配合 XeLaTeX 引擎，覆盖自动章节编号、目录、参考文献管理、LaTeX 自定义以及生产环境中总结出的常见问题排查模式。

主要能力

  • 自动章节编号与目录生成（--number-sections、--toc、--toc-depth）。
  • 参考文献与引用管理，无需手动重复（自动检测 references.bib 与 CSL 文件）。
  • 控制 LaTeX 输出中的表格格式与分页，代码块保持在同一页不跨页拆分。
  • 提供生产验证的 LaTeX 前导模板 table-spacing-template.tex（包含 booktabs、colortbl、ToC 修复）。
  • 提供通用自动检测构建脚本 build-pdf.sh。
  • 通过 Lua 过滤器隐藏 <details> 块，使其不出现在 PDF 输出中。
  • 构建前预检（pandoc、xelatex、文件是否存在）与构建后校验（文件大小、页数）。

使用方式

通用构建脚本

该技能在 $(cc-plugin-root doc-tools)/skills/pandoc-pdf-generation/assets/ 中提供资产。可在任意项目中创建符号链接后使用：

/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

选项：

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

横向 PDF 快速命令

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

隐藏内容

使用 --hide-details 从 PDF 输出中移除 <details> 块，适用于：图表源码块（保留在 markdown 中以便重新生成图表，但不在打印 PDF 中显示）、技术实现说明（在网页/markdown 视图中显示，打印讲义中隐藏）、可折叠区块（HTML <details> 标签在 PDF 中无法折叠渲染）。

用法：

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

ASCII 图表

ASCII 图表需要一致的字符对齐才能在 PDF 渲染中保持完整：一致使用制表符绘制字符，并保持每一行宽度相同。同时注意：将注释放在代码块之外，不要在图表代码块内添加如 # contains: file1, file2 的行内注释，它们会破坏对齐。

适用场景

  • 需要专业排版要求的 Markdown 转 PDF。
  • 需要自动章节编号与目录。
  • 需要管理引用与参考文献而不手动重复。
  • 需要控制 LaTeX 输出中的表格格式与分页。
  • 构建自动化 PDF 生成工作流。

验证清单

生成前：markdown 中无手动章节编号（使用 --number-sections）；注释在代码块之外。

生成后：打开 PDF 逐页目视检查；确认图表不跨页断开；检查章节编号正确（无 "1. 1. Title" 重复）；确认项目符号列表渲染为圆点而非行内破折号。

打印前：获得用户批准；确认方向偏好（横向/纵向）；确认单双面偏好。

打印工作流

始终让用户在打印前审阅 PDF。

打开审阅：

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

未经用户批准切勿打印。

限制与排查

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
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

该技能为自进化技能：若指令有误、参数漂移或需要变通方法，应立即修复该文件，但仅针对真实且可复现的问题更新。