Markdown 转 PDF 技能

将 Markdown 文件转换为精美的 PDF 文档，支持中文、代码高亮、自定义样式。

⭐ 推荐方案：WeasyPrint

完美支持中文，无需 LaTeX，自动处理依赖！

快速开始 # 转换 Markdown 为 PDF（推荐） bash /root/.OpenClaw/workspace/技能s/md2pdf/scripts/convert-weasyprint.sh 输入.md

# 指定输出文件名 bash /root/.OpenClaw/workspace/技能s/md2pdf/scripts/convert-weasyprint.sh 输入.md 输出.pdf

优点 ✅ 完美中文支持（使用 Noto Sans CJK 字体） ✅ 自动安装依赖（首次运行时自动安装） ✅ 专业排版样式（代码高亮、表格美化） ✅ 轻量级（无需 LaTeX，仅 Python） ✅ 跨平台（支持 Linux、macOS、Windows） 功能特性 ✅ Markdown 转 PDF ✅ 完美中文支持（无乱码） ✅ 代码语法高亮（深色主题） ✅ 专业表格样式（斑马纹、圆角） ✅ 多级标题样式 ✅ 引用块美化 ✅ 列表、链接、图片支持 ✅ 自定义 CSS 样式 使用方法 方法 1：WeasyPrint（推荐）⭐

适合场景： 需要完美中文显示、专业排版

# 使用 Bash 脚本（自动处理依赖） bash scripts/convert-weasyprint.sh document.md

# 指定输出文件 bash scripts/convert-weasyprint.sh document.md 输出.pdf

# 直接使用 Python 脚本 python3 scripts/convert-weasyprint.py 输入.md 输出.pdf

方法 2：Pandoc（备选）

适合场景： 已安装 LaTeX 环境

bash scripts/convert.sh 输入.md 输出.pdf

方法 3：简化 HTML

适合场景： 需要在浏览器中打印

bash scripts/convert-simple.sh 输入.md 输出.pdf

脚本说明 convert-weasyprint.sh ⭐

推荐使用 - WeasyPrint 方案，完美支持中文。

特性：

自动检测并安装 Python 依赖（markdown、weasyprint） 自动检测并安装中文字体（google-noto-sans-cjk-fonts） 专业的 CSS 样式（代码高亮、表格美化） 完整的错误处理

用法：

bash scripts/convert-weasyprint.sh <输入.md> [输出.pdf]

参数：

输入.md (必需): Markdown 文件路径 输出.pdf (可选): PDF 输出路径（默认：输入文件名.pdf）

示例：

# 转换单个文件 bash scripts/convert-weasyprint.sh README.md

# 指定输出路径 bash scripts/convert-weasyprint.sh README.md /tmp/readup.pdf

# 批量转换 for md in .md; do bash scripts/convert-weasyprint.sh "$md" done

convert-weasyprint.py

Python 转换脚本，被 convert-weasyprint.sh 调用，也可直接使用。

用法：

python3 scripts/convert-weasyprint.py <输入.md> [输出.pdf]

功能：

Markdown 解析（支持表格、代码块、列表） HTML 生成 CSS 样式应用 PDF 输出 convert.sh

Pandoc 传统方案（需要 LaTeX）。

用法：

bash scripts/convert.sh <输入.md> [输出.pdf]

前置要求：

pandoc xelatex (LaTeX) 中文字体 convert-simple.sh

简化版，生成 HTML 供浏览器打印。

用法：

bash scripts/convert-simple.sh <输入.md> [输出.pdf]

技术实现 WeasyPrint 方案

使用 Python 的 WeasyPrint 库进行转换：

# 1. Markdown → HTML html_content = markdown.markdown( md_content, 扩展s=['tables', 'fenced_code', 'nl2br', 'sane_列出s'] )

# 2. HTML + CSS → PDF HTML(string=html_content).write_pdf( 输出_file, stylesheets=[CSS(string='...')] )

CSS 样式特性：

中文字体：Noto Sans CJK SC 代码块：深色主题（#2c3e50 背景） 表格：蓝色表头 + 斑马纹 引用块：左边框 + 浅灰背景 响应式设计 Pandoc 方案

使用 pandoc 的 LaTeX 引擎：

pandoc 输入.md -o 输出.pdf \ --pdf-engine=xelatex \ -V CJKmA信息nt="Noto Sans CJK SC" \ -V geometry:margin=2cm

支持的 Markdown 特性 ✅ 标题（h1-h6） ✅ 段落和换行 ✅ 列表（有序、无序） ✅ 代码块（支持语法高亮） ✅ 表格 ✅ 链接和图片 ✅ 引用块 ✅ 水平线 ✅ 粗体和斜体 ✅ 自动链接 依赖管理 Python 依赖 # 自动安装（首次运行时） python3 -m pip 安装 markdown weasyprint

中文字体 # 自动安装（首次运行时） yum 安装 -y google-noto-sans-cjk-fonts

Pandoc（可选） # CentOS/RHEL yum 安装 -y pandoc

# Ubuntu/Debian apt-获取 安装 -y pandoc

故障排查 问题 1：中文显示为方块或乱码

解决方案（WeasyPrint）：

# 安装中文字体 yum 安装 -y google-noto-sans-cjk-fonts

# 验证字体 fc-列出 | grep "Noto Sans CJK"

解决方案（Pandoc）：

# 安装中文字体 yum 安装 -y google-noto-sans-cjk-sc-fonts

# 使用 xelatex pandoc 输入.md -o 输出.pdf --pdf-engine=xelatex -V CJKmA信息nt="Noto Sans CJK SC"

问题 2：Python 模块未找到

解决方案：

# 安装 Python 依赖 python3 -m pip 安装 markdown weasyprint

# 验证安装 python3 -c "导入 markdown, weasyprint; print('OK')"

问题 3：字体渲染问题

解决方案：

# 清除字体缓存 fc-缓存 -fv

# 重新安装字体 yum re安装 -y google-noto-sans-cjk-fonts

问题 4：PDF 文件过大

原因： WeasyPrint 会嵌入完整字体

解决方案：

使用子集化字体（需要额外工具） 或使用在线字体（需要网络连接） 或接受文件大小（通常 500KB-2MB） 完整示例 示例 1：基本转换 # 创建测试文件 cat > test.md << 'EOF' # 测试文档

这是中文测试文档。

功能列表

• 支持 Markdown
• 代码高亮
• 表格样式

示例 2：批量转换 # 转换目录下所有 Markdown 文件 for file in .md; do echo "转换: $file" bash scripts/convert-weasyprint.sh "$file" done

示例 3：集成到脚本 #!/bin/bash # 自动转换脚本

输入_DIR="/path/to/markdown/files" 输出_DIR="/path/to/pdf/输出"

mkdir -p "$输出_DIR"

for md in "$输入_DIR"/.md; do 输出="$输出_DIR/$(basename "$md" .md).pdf" bash /root/.OpenClaw/workspace/技能s/md2pdf/scripts/convert-weasyprint.sh "$md" "$输出" done

样式自定义 修改 CSS 样式

编辑 scripts/convert-weasyprint.py 中的 CSS 字符串：

css = CSS(string=''' / 修改字体大小 / body { font-size: 12pt; / 默认 11pt / }

/ 修改主色调 / h1, h2 { color: #e74c3c; / 改为红色 / }

/ 修改代码块背景 / pre { background-color: #34495e; / 深色主题 / } ''')

自定义模板

修改 HTML 模板以添加页眉、页脚等：

full_html = f"""

性能优化 加速转换 使用缓存： 保存字体缓存 批量处理： 合并多个 Markdown 为一个 PDF 并行处理： 使用 GNU parallel # 并行转换 ls .md | parallel -j 4 bash scripts/convert-weasyprint.sh {}

相关技能 feishu-doc: 飞书文档操作 feishu-drive: 飞书云文件管理 md2pdf: Markdown 转 PDF（本技能） 常见问题

Q: WeasyPrint 和 Pandoc 哪个更好？

A: 推荐使用 WeasyPrint：

✅ 完美中文支持（无需配置） ✅