mkbook

Markdown 电子书生成工具 — 一份源稿一键产出高质量排版的 PDF与静态 HTML 站点, 数学公式只需写 LaTeX。

设计与方案细节: docs/mkbook-analysis.md

特性

• PDF 是一等产物, 调用 Tectonic (自包装 XeLaTeX) 编译, 中文用 ctex 文档类
• 数学公式只用 LaTeX 语法 — 行内 $E = mc^2$, 块级 $$ ... $$, 一份源跨 PDF / HTML 渲染
  • PDF 端: 数学源 1:1 原样进 xelatex, 中间不经过任何转义
  • HTML 端: 服务端 KaTeX 预渲染
• 支持 GFM (表格、删除线、任务列表)
• 显式 SUMMARY.md 决定章节顺序与结构, 类 mdBook 风格
• 单包零运行时配置, 装好就用

安装

# 当前: 本仓库内开发
pnpm install
pnpm build
node dist/cli.js --help

# 未来: 发布到 npm 后
npm i -g mkbook

可选系统依赖:

• Tectonic — PDF 渲染必需; 没装时仍可生成 .tex 中间产物, 但跳过编译
  • macOS: brew install tectonic
  • 或用 xelatex / lualatex (在 book.toml 里改 [pdf].engine)

快速上手

mkbook init my-book --title "我的书"
cd my-book
mkbook build              # 出 PDF + HTML
mkbook build -t pdf       # 只出 PDF
mkbook build -t html      # 只出 HTML
mkbook clean              # 清理 out/

输出:

out/
  ├── .tex/
  │   ├── main.tex                 # 主 LaTeX 源
  │   ├── fragments/<kind>-*.tex   # 每章独立片段, debug 用
  │   └── main.pdf                 # Tectonic 中间产物
  ├── my-book.zh.pdf               # 最终 PDF
  └── html/
      ├── index.html
      ├── face-*.html
      ├── chap-*.html
      └── appx-*.html

项目结构

my-book/
├── book.toml              # 配置 (书名/作者/PDF 模板/语言)
├── SUMMARY.md             # 章节目录, 决定顺序与结构
└── src/
    ├── face/              # 前言 (frontmatter)
    ├── chap/              # 正文 (mainmatter)
    ├── appx/              # 附录 (appendix)
    ├── images/            # 图片资源
    └── resources/         # 其他资源

book.toml

[book]
title  = "我的书"
author = "作者名"
date   = "\\today"
lang   = "zh"               # zh | en

[pdf]
template      = "book"      # book | article | novel | blog
documentClass = "ctexbook"  # ctexbook (中文书) / ctexart / book / article
classOptions  = "oneside,openany,UTF8"   # 不再夹带 a5paper 等纸张项, 纸张走下面的 paper
engine        = "tectonic"  # tectonic | xelatex | lualatex
final         = false       # true: 跑两遍 (生成索引/参考文献)

# 页面层: LaTeX / Chromium / HTML 三端共享, 保证渲染一致
paper         = "A4"        # A0..A6 | B5 | B6 | Letter | Legal | Tabloid (article 上限)
fontSize      = "12pt"      # 10pt | 11pt | 12pt (12pt = 小四号)
measure       = "38em"      # 文本列宽度, margin 自动反推 (见 docs/page-geometry)

[html]
theme = "default"

SUMMARY.md

类 mdBook 风格. 标题段决定章节归类 (前言 / 正文 / 附录), 列表里的链接决定顺序与文件:

# Summary

[前言](face/intro.md)

## 正文
- [安装](chap/install.md)
- [Hello World](chap/hello.md)
- 第二部分
  - [进阶](chap/advanced.md)

## 附录
- [术语表](appx/glossary.md)

文件路径以 face/ / chap/ / appx/ 开头时, kind 自动识别 (兼容多种 SUMMARY 写法)。

命令面 (参照 mdBook)

| 命令 | 状态 | 说明 | |------|------|------| | mkbook init [dir] | ✅ v0.1 | 创建项目脚手架 | | mkbook build [dir] | ✅ v0.1 | 全量构建 (PDF + HTML) | | mkbook clean [dir] | ✅ v0.1 | 删除 out/ | | mkbook watch [dir] | 🚧 v0.2 | 监听重编 | | mkbook serve [dir] | 🚧 v0.2 | 起本地预览, 复用 VitePress dev server | | mkbook test [dir] | 🚧 v0.2 | 校对: 链接 / 孤儿文件 / SUMMARY 一致性 | | mkbook new <kind> <slug> | 🚧 v0.2 | 新建章节并登记到 SUMMARY | | mkbook completions <shell> | 🚧 v0.2 | shell 补全 |

Markdown → LaTeX 的转换

PDF Renderer 用一个自写的 mdast → LaTeX visitor, 不经过 pandoc。 原因与对比见 docs/mkbook-analysis.md §4.5。

支持的 mdast 节点 → LaTeX 映射 (摘要):

| Markdown | LaTeX | |----------|-------| | # H1 ~ ###### H6 | \chapter{} ~ \subparagraph{} | | *em* | \emph{} | | **bold** | \textbf{} | | ~~del~~ | \sout{} | | `code` | \verb|code| (自动选不冲突的分隔符) | | 围栏代码块 | lstlisting 环境 | | [txt](url) | \href{url}{txt} | | ![alt](src) | figure + \includegraphics + \caption | | 列表 | itemize / enumerate | | 引用 | quote | | --- | \par\hrulefill\par | | GFM 表格 | tabular (按对齐 l/c/r) | | $x$ (inline math) | $x$ 原样 | | $$x$$ (display math) | \[ x \], 或检测到 \begin{align} 等环境时保留环境 |

关键: 数学节点的源码 1:1 落地, 不做任何转义 ($a_b \sum_{i=1}^n$ 进 $a_b \sum_{i=1}^n$ 出, & _ ^ 都不会被替换), 这是项目硬约束。

开发

pnpm install
pnpm test               # vitest run
pnpm test:watch
pnpm build              # tsc → dist/
pnpm mkbook -- ...      # 直接跑源码 (tsx)
pnpm docs:dev           # 起 VitePress 文档站

测试覆盖:

• src/core/config.test.ts — 配置合并、i18n、校验
• src/core/summary.test.ts — SUMMARY.md 解析、kind 推断
• src/renderers/pdf/mdast-to-latex.test.ts — 27 个节点级转换测试

路线图

详见 docs/roadmap.md. 简略:

• v0.3 (当前): init / build (PDF + HTML) / clean / watch / serve / test / new / stats
• v0.4: frontmatter / mkbook completions / 错误诊断小修
• v0.5: PDF 单章增量构建 / 结构化诊断 / PDF 预览
• v0.6: Mermaid / 图片优化 / 双主题 / 主题层抽象
• v0.7: 插件机制 / Renderer 接口冻结
• v1.0: npm + Docker + publish + i18n + CI

EPUB 与独立 slides 渲染器已从路线图移除 — HTML 演示模式覆盖讲方案的场景, PDF 覆盖归档/外发场景.

License

MIT