Baymax md2pdf

将 Markdown 转换为适合阅读和交付的 PDF，重点处理中文、英文、公式、代码和长文档目录。

工作原理 / How it works

_{主要处理路径、异常分支和人工检查点。 / The main processing path, exception branches, and human review points.}

主要能力

• Markdown 与 YAML frontmatter
• 中英文混排与可选的盘古式空格
• KaTeX 数学公式
• Shiki 代码高亮
• 脚注、任务列表、提示块与引用
• 目录、页眉、页脚和 A4 打印样式
• 本地预览与文件变化监听

安装

需要 Node.js 20 或更高版本。

git clone https://github.com/BaymaxStudio/baymax-md2pdf.git
cd baymax-md2pdf
npm ci
npm link

安装后可以直接运行 md2pdf。不执行 npm link 时，也可以使用 node bin/md2pdf.js。

使用

md2pdf document.md -o document.pdf

启动本地预览：

md2pdf document.md --watch --port 3000

关闭目录或中英文空格处理：

md2pdf document.md --no-toc --no-pangu

Frontmatter

---
title: 文档标题
subtitle: 副标题
author: 作者
date: 2026-08-29
toc: true
cover: false
section_numbering: true
---

正文中也可以使用 [[toc]] 指定目录位置。

字体

仓库不分发第三方字体文件。缺少字体时会使用系统字体，不影响基本转换。若需要项目原定的编辑排版效果，可运行：

npm run build:fonts

字体来源和许可说明见 assets/fonts/README.md。Source Han Serif 中文子集需要按其中说明单独准备。

验证

npm test
npm run test:smoke

核心测试覆盖 frontmatter、HTML 转义、中英文间距和引用处理；冒烟测试会在临时目录生成真实 PDF，并检查文件头和文件大小。

项目角色

我定义了面向中文长文档的排版需求、CLI 工作流和验收方式，并使用 AI 编程工具协助实现与调试。该工具已用于研究报告、使用指南和课程材料的实际交付。

许可证

MIT License