md2book

Markdown to Professional PDF Book Converter

将 Markdown 格式的技术书籍/教程转换为专业排版的 PDF 电子书。

何时使用

• 用户提供 Markdown 文件路径，要求转为 PDF
• 用户提到"导出 PDF"、"生成电子书"、"制作 PDF"
• 用户需要书籍级别的排版输出

快速命令

node scripts/md2book.js <input.md>
node scripts/md2book.js <input.md> --theme <minimal|academic|playful>
node scripts/md2book.js <input.md> --output <path.pdf>
node scripts/md2book.js <input.md> --verbose

完整工作流程

Phase 1: 检查输入

1. 确认用户提供了 Markdown 文件路径
2. 检查文件是否存在
3. 检查文件是否有 YAML frontmatter（title, author, date 等）
4. 如果没有 frontmatter，询问用户补充关键信息（书名、作者）

Phase 2: 确认参数

向用户确认：

• 主题风格（默认 minimal）：
  • minimal — 极简科技风（大量留白，黑白灰，适合技术书）
  • academic — 经典学术风（衬线字体，暖色纸张，稳重专业）
  • playful — 活泼插画风（色彩丰富，渐变装饰）
• 输出路径（默认与 MD 文件同级目录）
• 是否需要目录（默认生成）

Phase 3: 执行转换

cd /Users/bytedance/Documents/CC/huashu/huashu-bookwriter-skill
node scripts/md2book.js <input.md> --theme <theme> --verbose

Phase 4: 验证输出

1. 检查 PDF 文件是否生成
2. 验证以下项目：
   • [ ] 封面正常渲染（书名、作者可见）
   • [ ] 版权页包含完整信息
   • [ ] 目录生成正确
   • [ ] 每个 # 章节从新页面开始
   • [ ] 中文无乱码
   • [ ] 页码连续
   • [ ] 代码块/表格未被截断
3. 如果有问题，检查错误日志并修复

输入文件格式

Markdown 文件应包含 YAML frontmatter：

---
title: 书名
subtitle: 副标题（可选）
author: 作者名
publisher: 出版社（可选）
version: v1.0
date: 2026-04-10
isbn: 978-0-000000-00-0（可选）
description: 一句话简介
---

# 第一章 引言

正文内容...

## 1.1 概述

更多内容...

支持的 Markdown 特性

• 标准 GFM（表格、代码块、列表）
• 代码语法高亮（highlight.js）
• Callout 提示框：[!INFO], [!TIP], [!WARNING], [!DANGER]
• 图片和图注
• 引用块
• 自动目录生成

视觉主题说明

minimal（极简科技风）

• 纯白背景，黑白灰色调
• 思源宋体正文 + 黑体标题
• 简洁的装饰线条
• 适合：技术文档、编程教程

academic（经典学术风）

• 暖色纸张质感背景
• 深红色强调色
• 经典衬线字体
• 适合：理论著作、学术专著

playful（活泼插画风）

• 渐变彩色封面
• 圆角卡片设计
• 丰富的色彩变化
• 适合：入门教程、科普读物

故障排查

中文显示为方框

• 检查系统是否安装了思源宋体或宋体
• macOS 自带 Songti SC 和 STSong
• 可在 references/font-guide.md 中查看字体配置

Playwright 浏览器未安装

cd /Users/bytedance/Documents/CC/huashu/huashu-bookwriter-skill/scripts
npx playwright install chromium

依赖未安装

cd /Users/bytedance/Documents/CC/huashu/huashu-bookwriter-skill/scripts
npm install

PDF 内容为空

• 检查 Markdown 文件编码是否为 UTF-8
• 使用 --verbose 查看转换日志
• 检查 frontmatter 格式是否正确

Chromium 浏览器找不到

• 脚本会自动检测 ~/Library/Caches/ms-playwright/ 下的 Chromium
• 如果未安装，运行 npx playwright install chromium
• 确认安装后重新运行转换命令

相关文件

• scripts/md2book.js — 主转换脚本
• scripts/package.json — 依赖配置
• assets/styles/book.css — 书籍核心样式（分页、页眉页脚）
• assets/styles/typography.css — 中文字体排版
• assets/styles/components.css — 表格/代码块/引用/Callout 样式
• assets/styles/themes/ — 三套视觉主题（minimal, academic, playful）
• references/font-guide.md — 字体配置参考