Markdown 转 PDF 技能

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

⭐ 推荐方案：WeasyPrint

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

快速开始

bash

转换 Markdown 为 PDF（推荐）

bash /root/.openclaw/workspace/skills/md2pdf/scripts/convert-weasyprint.sh input.md

指定输出文件名

bash /root/.openclaw/workspace/skills/md2pdf/scripts/convert-weasyprint.sh input.md output.pdf

优点

• - ✅ 完美中文支持（使用 Noto Sans CJK 字体）
• ✅ 自动安装依赖（首次运行时自动安装）
• ✅ 专业排版样式（代码高亮、表格美化）
• ✅ 轻量级（无需 LaTeX，仅 Python）
• ✅ 跨平台（支持 Linux、macOS、Windows）

功能特性

• - ✅ Markdown 转 PDF
• ✅ 完美中文支持（无乱码）
• ✅ 代码语法高亮（深色主题）
• ✅ 专业表格样式（斑马纹、圆角）
• ✅ 多级标题样式
• ✅ 引用块美化
• ✅ 列表、链接、图片支持
• ✅ 自定义 CSS 样式

使用方法

方法 1：WeasyPrint（推荐）⭐

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

bash

使用 Bash 脚本（自动处理依赖）

bash scripts/convert-weasyprint.sh document.md

指定输出文件

bash scripts/convert-weasyprint.sh document.md output.pdf

直接使用 Python 脚本

python3 scripts/convert-weasyprint.py input.md output.pdf

方法 2：Pandoc（备选）

适合场景： 已安装 LaTeX 环境

bash
bash scripts/convert.sh input.md output.pdf

方法 3：简化 HTML

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

bash
bash scripts/convert-simple.sh input.md output.pdf

脚本说明

convert-weasyprint.sh ⭐

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

特性：

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

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

参数：

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

示例：
bash

转换单个文件

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 调用，也可直接使用。

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

功能：

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

convert.sh

Pandoc 传统方案（需要 LaTeX）。

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

前置要求：

• - pandoc
• xelatex (LaTeX)
• 中文字体

convert-simple.sh

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

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

技术实现

WeasyPrint 方案

使用 Python 的 WeasyPrint 库进行转换：

python

1. Markdown → HTML

html_content = markdown.markdown(
md_content,
extensions=[tables, fencedcode, nl2br, sanelists]
)

2. HTML + CSS → PDF

HTML(string=htmlcontent).writepdf( output_file, stylesheets=[CSS(string=...)] )

CSS 样式特性：

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

Pandoc 方案

使用 pandoc 的 LaTeX 引擎：

bash
pandoc input.md -o output.pdf \
--pdf-engine=xelatex \
-V CJKmainfont=Noto Sans CJK SC \
-V geometry:margin=2cm

支持的 Markdown 特性

• - ✅ 标题（h1-h6）
• ✅ 段落和换行
• ✅ 列表（有序、无序）
• ✅ 代码块（支持语法高亮）
• ✅ 表格
• ✅ 链接和图片
• ✅ 引用块
• ✅ 水平线
• ✅ 粗体和斜体
• ✅ 自动链接

依赖管理

Python 依赖

bash

自动安装（首次运行时）

python3 -m pip install markdown weasyprint

中文字体

bash

自动安装（首次运行时）

yum install -y google-noto-sans-cjk-fonts

Pandoc（可选）

bash

CentOS/RHEL

yum install -y pandoc

Ubuntu/Debian

apt-get install -y pandoc

故障排查

问题 1：中文显示为方块或乱码

解决方案（WeasyPrint）：
bash

安装中文字体

yum install -y google-noto-sans-cjk-fonts

验证字体

fc-list | grep Noto Sans CJK

解决方案（Pandoc）：
bash

安装中文字体

yum install -y google-noto-sans-cjk-sc-fonts

使用 xelatex

pandoc input.md -o output.pdf --pdf-engine=xelatex -V CJKmainfont=Noto Sans CJK SC

问题 2：Python 模块未找到

解决方案：
bash

安装 Python 依赖

python3 -m pip install markdown weasyprint

验证安装

python3 -c import markdown, weasyprint; print(OK)

问题 3：字体渲染问题

解决方案：
bash

清除字体缓存

fc-cache -fv

重新安装字体

yum reinstall -y google-noto-sans-cjk-fonts

问题 4：PDF 文件过大

原因： WeasyPrint 会嵌入完整字体

解决方案：

• - 使用子集化字体（需要额外工具）
• 或使用在线字体（需要网络连接）
• 或接受文件大小（通常 500KB-2MB）

完整示例

示例 1：基本转换

bash

创建测试文件

cat > test.md << EOF

测试文档

这是中文测试文档。

功能列表

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

列1	列2
A	B

\\\python
print(Hello, World!)
\\\
EOF

转换为 PDF

bash scripts/convert-weasyprint.sh test.md

示例 2：批量转换

bash

转换目录下所有 Markdown 文件

for file in *.md; do
echo 转换: $file
bash scripts/convert-weasyprint.sh $file
done

示例 3：集成到脚本

bash
#!/bin/bash

自动转换脚本

INPUT_DIR=/path/to/markdown/files
OUTPUT_DIR=/path/to/pdf/output

mkdir -p $OUTPUT_DIR

for md in $INPUT_DIR/*.md; do
output=$OUTPUT_DIR/$(basename $md .md).pdf
bash /root/.openclaw/workspace/skills/md2pdf/scripts/convert-weasyprint.sh $md $output
done

样式自定义

修改 CSS 样式

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

python
css = CSS(string=
/ 修改字体大小 /
body {
font-size: 12pt; /*