md2pdf-tool 0.1.0

Convert Markdown to a styled, Chinese-friendly A4 PDF with QA previews.

md2pdf

Markdown 转 PDF 工具，专为中文文档优化：

1. Pandoc 把 Markdown 转成带目录的 HTML。
2. md2pdf/style.css 负责中文字体、封面、目录、标题、引用块、表格和分页样式。
3. Playwright / headless Chrome 把 HTML 打印成 A4 PDF。
4. PyMuPDF + Pillow 渲染 QA 图片和 summary.txt，用于检查页数、页面尺寸、乱码和抽检页面。

安装

需要先准备两个系统依赖（pip 无法安装）：

• pandoc：brew install pandoc（macOS）/ apt install pandoc（Debian/Ubuntu）。
• 浏览器：装好 Python 包后运行 playwright install chromium，让 Playwright 下载自带的 Chromium；macOS 上若已装 Google Chrome 也可直接复用。

然后安装本工具。发布名是 md2pdf-tool（PyPI 上 md2pdf 已被占用），命令仍是 md2pdf。

已发布后，最终用户二选一：

# Homebrew（个人 tap）
brew install <用户名>/md2pdf/md2pdf
playwright install chromium

# 或 pipx
pipx install md2pdf-tool
playwright install chromium

从源码安装 / 开发：

pipx install .          # 从仓库目录安装，得到全局 md2pdf 命令
# 或可编辑安装：
python -m venv .venv && source .venv/bin/activate
pip install -e .
playwright install chromium

发布到 PyPI 和搭建 Homebrew tap 的完整步骤见 PUBLISHING.md。

使用

安装后直接用 md2pdf 命令：

md2pdf docs/requirements.md

不传输出路径时，默认输出到同目录同名 .pdf；不传 --title 时，默认用文件名。

也可以用 gen_pdf.sh 包装脚本——它会自动读取 Markdown 第一个一级标题作为封面标题：

./gen_pdf.sh docs/requirements.md docs/requirements.pdf
./gen_pdf.sh --dry-run docs/requirements.md   # 只打印将要执行的命令

需要手动指定标题、副标题、日期或必检文本时，传对应参数：

md2pdf docs/requirements.md \
  --output docs/requirements.pdf \
  --title "4D交互式电子手册平台需求说明" \
  --subtitle "面向大型企业私有化部署的创作、发布、播放与反馈闭环系统" \
  --date "2026-06-03" \
  --required-text "十八、最终一句话目标"

未安装时，也可以从仓库根目录用模块方式运行（需 pip install -e . 或设置 PYTHONPATH=src）：

python -m md2pdf.build_pdf path/to/input.md --output path/to/output.pdf

输出

生成后会输出（以 requirements 为例）：

• PDF：docs/requirements.pdf
• 中间 HTML：<build-dir>/requirements.html
• QA 摘要：<build-dir>/qa/summary.txt
• 页面抽检图和缩略图：<build-dir>/qa/*.png

<build-dir> 默认放在输出 PDF 旁边的 .build/<stem>/（用户可写，不会写进只读的安装目录）。需要指定别处时用 --build-dir，例如 --build-dir ./.md2pdf-build。

依赖

• pandoc
• Python 包：playwright、PyMuPDF（fitz）、Pillow（随 pip install 自动安装）
• Google Chrome 或 Playwright Chromium

Pandoc 可能提示 Could not load translations for zh-CN，这不影响中文内容生成和 PDF 文本提取。

测试

pip install -e .
python -m unittest discover -s tests -v