pdf-generation

PDF 生成

概述

使用 Pandoc 和 Eisvogel 模板样式，从 Markdown 文件生成专业 PDF。支持英语和俄语文档，可自定义主题、目录和专业字体排版，其中俄语文本使用 EB Garamond 字体。

快速开始

基本命令：

# Desktop/Print PDF (A4 format)
pandoc doc.md -o doc.pdf --pdf-engine=xelatex --toc --toc-depth=2 -V geometry:margin=2.5cm -V fontsize=11pt -V documentclass=article

# Mobile-friendly PDF (6x9 phone screen optimized)
pandoc doc.md -o doc-mobile.pdf --pdf-engine=xelatex --toc --toc-depth=2 -V geometry:paperwidth=6in -V geometry:paperheight=9in -V geometry:margin=0.5in -V fontsize=10pt -V linestretch=1.2

# Russian PDF with EB Garamond
pandoc doc-ru.md -o doc.pdf --pdf-engine=xelatex --toc --toc-depth=2 -V geometry:margin=2.5cm -V fontsize=11pt -V documentclass=article -V mainfont="EB Garamond"

# Russian Mobile PDF
pandoc doc-ru.md -o doc-mobile.pdf --pdf-engine=xelatex --toc --toc-depth=2 -V geometry:paperwidth=6in -V geometry:paperheight=9in -V geometry:margin=0.5in -V fontsize=10pt -V linestretch=1.2 -V mainfont="EB Garamond"

文档主题颜色

• 白皮书 - 蓝色（1e3a8a）
• 营销 - 绿色（059669）
• 研究 - 紫色（7c3aed）
• 技术 - 灰色（374151）

YAML Frontmatter 示例

---
title: "Document Title"
subtitle: "Subtitle"
author: "Author"
date: "2025-11-18"
titlepage: true
titlepage-color: "1e3a8a"
titlepage-text-color: "ffffff"
book: true
---

完整模板请参阅 references/frontmatter_templates.md。

Markdown 格式最佳实践

为获得最佳 PDF 渲染效果，请确保：

1. 列表前留空行 - 正确渲染列表的必要条件
2. 标题后留空行 - 改善间距
3. 嵌套列表缩进 - 子项目使用 3 个空格

常见的 Claude Code 模式

冒号后的列表需要留空行：

Your data spans 9 years with complete tracking:

- Item 1
- Item 2

冒号后不留空行时，会渲染为行内文本。

自动修复

使用预处理脚本：

scripts/fix_markdown.py input.md output.md

自动检测并修复：

• 冒号后的列表（Claude Code 格式）
• 标题后的列表
• 嵌套列表间距

布局选项

桌面/打印布局（A4）

• 纸张：210mm x 297mm（A4）
• 页边距：2.5cm
• 字号：11pt
• 最适合：打印、在大屏幕上阅读、归档

移动布局（针对手机优化）

• 纸张：6in x 9in（手机纵横比）
• 页边距：0.5in（尽量减少，以节省屏幕空间）
• 字号：10pt，行距为 1.2
• 最适合：在手机/平板电脑上阅读、Telegram/消息应用

Telegram Bot 的默认设置：通过 Telegram 发送的所有 PDF 默认使用移动布局，除非用户明确要求打印/桌面版本。

生成工作流

工作流 1：简单 PDF

1. 检查上下文（Telegram = 移动布局，否则使用桌面布局）
2. 检查是否为俄语文档（如果是，则使用 EB Garamond）
3. 运行相应的 pandoc 命令
4. 验证输出

工作流 2：专业标题页

1. 添加包含主题颜色的 YAML frontmatter
2. 包含元数据（标题、作者、日期）
3. 选择布局（移动或桌面）
4. 使用 xelatex 生成

工作流 3：使用脚本

scripts/generate_pdf.py doc.md -t white-paper
scripts/generate_pdf.py doc.md -t marketing --russian
scripts/generate_pdf.py doc.md --mobile  # Mobile layout

资源

• scripts/generate_pdf.py - 自动生成
• references/frontmatter_templates.md - YAML 模板
• references/pandoc_reference.md - 命令参考

故障排除

安装 pandoc：brew install pandoc 安装 LaTeX：brew install --cask mactex

适合移动设备的 PDF

若要在手机和平板电脑上阅读，请使用移动布局选项：

# Using script (recommended)
scripts/generate_pdf.py doc.md --mobile

# Direct pandoc command
pandoc doc.md -o doc-mobile.pdf \
  --pdf-engine=xelatex \
  --toc --toc-depth=2 \
  -V geometry:paperwidth=6in \
  -V geometry:paperheight=9in \
  -V geometry:margin=0.5in \
  -V fontsize=10pt \
  -V linestretch=1.2 \
  -V colorlinks=true \
  -V linkcolor=blue \
  -V urlcolor=blue

移动布局功能：

• 6x9 英寸页面尺寸（适合移动屏幕）
• 10pt 字号（在较小屏幕上清晰易读）
• 0.5in 页边距（最大化内容区域）
• 1.2 行距（提升可读性）
• 自动生成 -mobile.pdf 文件名后缀

适合使用移动布局的场景：

• 通过 Telegram/消息应用分享研究资料
• 在手机或平板电脑上阅读
• 创建便于携带的参考文档
• 随时随地快速浏览

默认上下文：通过 Telegram bot 生成 PDF 时，默认使用移动布局，以便在移动设备上获得最佳阅读体验。