Markdown 转 PDF 转换器（完整版）

概述

使用 完整的 Unicode 支持、中文字体及 彩色 emoji（共 3660 个 emoji，含全部变体），将 Markdown 文档转换为专业级 PDF。基于 Pandoc + WeasyPrint 实现，并内置本地 Twemoji 缓存，首次运行后即可离线工作。

快速开始

将一个 Markdown 文件转换为 PDF：

bash scripts/md2pdf-local.sh input.md output.pdf

仅首次运行时：从 GitHub 下载约 150MB 的 emoji 资源（Twemoji 14.0.0）。后续运行完全离线。

示例：

bash scripts/md2pdf-local.sh report.md report.pdf

特性

• ✅ 完整 Unicode 支持（中文、日文、韩文）
• ✅ 完整 emoji 支持（Twemoji 14.0.0，3660 个彩色 PNG）
• ✅ 全部 emoji 变体（肤色、发型、地区旗帜等）
• ✅ 首次配置完成后支持 离线运行
• ✅ 具备页码的 专业 PDF 排版
• ✅ 支持 代码高亮、表格、引用块
• ✅ 基于 Python 预生成的查找表实现 精准 emoji 映射

技术细节

依赖项

• Pandoc —— 通用文档格式转换器
• WeasyPrint —— CSS 到 PDF 渲染器
• Python 3 —— 用于生成 emoji 映射表
• wget —— 用于下载 emoji 资源（仅首次运行需要）

工作原理

1. 首次运行：将 Twemoji 14.0.0 下载至 ~/.cache/md2pdf/emojis/
2. Python 脚本：生成 emoji 字符到文件名的映射表（emoji_mapping.json）
3. Pandoc：通过 Lua 过滤器将 Markdown 转换为 HTML，该过滤器将 emoji 字符替换为本地图片引用
4. WeasyPrint：使用以下资源将 HTML 渲染为 PDF：
   • AR PL UMing CN 字体渲染中文字符
   • 本地 emoji 图片（PNG 格式，72×72 像素，彩色）
   • 专业级 CSS 样式

Emoji 缓存路径

~/.cache/md2pdf/
├── emojis/                    # 3660 个彩色 PNG 文件
│   ├── 0023-fe0f-20e3.png
│   ├── 1f600.png
│   └── ...
└── emoji_mapping.json         # Emoji 到文件名的映射表
    {
      "🙀": "1f600.png",
      "⌛": "0023-fe0f-20e3.png",
      ...
    }

Emoji 映射机制

Python 脚本 generate_emoji_mapping.py 扫描全部 Twemoji 文件，构建 emoji 字符与 PNG 文件名之间的精确映射关系。该机制确保即使对肤色、地区标识符等复杂变体，也能实现准确的 emoji 替换。

字体配置

主用中文字体：AR PL UMing CN

备用字体：Noto Sans SC、Noto Sans CJK SC、Microsoft YaHei

等宽字体：Menlo、Monaco

版本历史

v2.0（当前版本）

• ✅ 升级至 Twemoji 14.0.0（完整版）
• ✅ 提供 3660 个彩色 emoji（含全部变体）
• ✅ 使用 Python 预生成映射表，保障 emoji 替换精度
• ✅ 修复黑白 emoji 显示问题
• ✅ 完整支持 emoji 变体（肤色、发型等）

v1.0（旧版本）

• 采用 emoji-datasource-google（约 2000–3000 个 emoji）
• 基于十六进制的简单文件名匹配（对变体支持不准确）
• 部分 emoji 以 Unicode 字符形式显示（黑白）

故障排查

字体问题

若中文字符显示异常，请确认已安装 AR PL UMing CN 字体：

# Ubuntu/Debian
sudo apt-get install fonts-arphic-uming

# 检查是否已安装
fc-list | grep "AR PL UMing"

Emoji 未显示

1. 检查 emoji 缓存是否存在：ls ~/.cache/md2pdf/emojis/
2. 检查映射文件是否存在：ls ~/.cache/md2pdf/emoji_mapping.json
3. 若缺失，删除缓存并重新运行：rm -rf ~/.cache/md2pdf
4. 验证 emoji 文件是否存在：ls ~/.cache/md2pdf/emojis/1f600.png

Emoji 显示为黑白

此问题已在 v2.0 中 修复。如仍出现黑白 emoji，请执行以下操作：

1. 确认您正在使用 v2.0 脚本：

   grep "TWEMOJI_VERSION" scripts/md2pdf-local.sh
   # 应输出：TWEMOJI_VERSION="14.0.0"
   

2. 清除缓存并重新生成：

   rm -rf ~/.cache/md2pdf
   bash scripts/md2pdf-local.sh test.md test.pdf
   

WeasyPrint 报错

请安装缺失的依赖项：

# Ubuntu/Debian
sudo apt-get install python3-weasyprint

# 或使用 pip 安装
pip3 install weasyprint

Python 脚本报错

若 generate_emoji_mapping.py 执行失败：

# 检查 Python 版本
python3 --version
# 应为 Python 3.6 或更高版本

# 检查 emoji 缓存目录
ls ~/.cache/md2pdf/emojis

资源说明

scripts/ 目录

md2pdf-local.sh —— 主转换脚本，自动完成 emoji 缓存与映射

generate_emoji_mapping.py —— 生成 emoji 查找表的 Python 脚本

使用方式：可从任意路径直接执行（脚本内部使用绝对路径）：

bash /path/to/skills/md2pdf-converter/scripts/md2pdf-local.sh input.md output.pdf

核心特性：

• 自动下载并缓存 Twemoji
• Python 预生成 emoji 映射表（高精度）
• 通过 Lua 过滤器实现 emoji 替换
• 采用专业 CSS 样式生成输出
• 自动清理临时文件

对比：v1.0 vs v2.0

性能表现

• 首次运行：约 150MB 下载量，耗时 10–30 秒（取决于网络状况）
• 后续运行：完全离线，转换耗时以秒计
• 内存占用：emoji 缓存约占用 150MB 内存
• PDF 生成速度：每页 1–5 秒

限制条件

• Twemoji 14.0.0 之后新增的 emoji 将以 Unicode 字符形式显示
• 首次运行需联网（用于下载 Twemoji）
• emoji 缓存大小：约 150MB（3660 个 72×72 像素 PNG 文件）