Pro Git 2 多格式电子书一键构建完全指南：HTML、PDF、EPUB 全搞定
【免费下载链接】progit2-zh项目地址: https://gitcode.com/gh_mirrors/pr/progit2-zh
progit2-zh 是经典 Git 教程《Pro Git 2》的中文版仓库。除了直接翻 AsciiDoc 源码，你还可以用一条命令把它构建成 HTML、PDF、EPUB、MOBI、FB2 五种格式的电子书，塞进浏览器、Kindle，或者干脆打印成纸质书。下面带你从零走通整个流程。
📖 先看看成品长什么样
构建完成后，仓库根目录会多出五个文件，各管各的阅读场景：
| 输出文件 | 格式 | 适用场景 |
|---|---|---|
| progit.html | 网页 | 浏览器直接打开，支持全文搜索与目录跳转 |
| progit.pdf | 打印版 | 桌面阅读、打印装订 |
| progit.epub | 电子书包 | Kobo、苹果图书等阅读器 |
| progit.mobi | Kindle 格式 | 各类 Kindle 设备 |
| progit.fb2.zip | FB2 | 支持 FB2 的阅读软件 |
书稿里穿插了大量手绘风格的示意图，转换进上述格式后依然清晰可读：
🔧 倒推回去：先把 Ruby 环境装好
整个构建基于 Ruby + Rake，准备阶段只有两步：
git clone https://gitcode.com/gh_mirrors/pr/progit2-zh cd progit2-zh bundle installbundle install会按 Gemfile 的声明装好全部依赖，其中几个关键角色是：
- asciidoctor：核心转换引擎，负责把源稿变成文档
- asciidoctor-pdf / asciidoctor-epub3 / asciidoctor-fb2：三种格式的处理器
- rake：把构建步骤编排成可调用的任务
- html-proofer、epubcheck-ruby：构建完成后的自动校验
- asciidoctor-pdf-cjk 系列字体包：保证 PDF 里的中文显示正常，而不是一个个豆腐块
⚡ 一条命令构建全部格式
环境就绪后，在仓库根目录执行：
rake book:build这条命令背后连做了四件事：用git describe取出版本号、结合当前日期写入文档头部；重新生成贡献者名单（book/contributors.txt）；依次调用各格式转换器；最后对 HTML 和 EPUB 跑一遍自动校验。其中 PDF 环节最耗时，构建脚本自己都会提示 "this one takes a while"，耐心等即可。
如果只想要某一种格式，直接调用对应子任务就行：
| 命令 | 产物 |
|---|---|
| rake book:build_html | progit.html |
| rake book:build_pdf | progit.pdf |
| rake book:build_epub | progit.epub |
| rake book:build_mobi | progit.mobi |
| rake book:build_fb2 | progit.fb2.zip |
| rake book:clean | 清空全部生成文件 |
📚 生成完成之后：怎么用、怎么改
- HTML：双击 progit.html 就能读，浏览器原生支持全文搜索。
- PDF：版面固定，最适合打印或平板阅读。
- EPUB / MOBI：通过同步工具或邮箱发送到对应阅读器即可。
想换一套外观？样式集中在 theme/ 目录下：HTML 对应 theme/html/html.css，PDF 对应 theme/pdf/pdf.css 与 theme/pdf/pdf.xsl，EPUB 对应 theme/epub/epub.css。改完 CSS 重新跑一次对应的构建任务即可生效。
🩹 清理与常见问题
- 想推倒重来：
rake book:clean会删掉所有生成文件，包括贡献者名单缓存。 - 构建特别慢：PDF 环节本来就重，属正常现象，别中途杀掉。
- gem 版本冲突：删掉 Gemfile.lock，重新执行
bundle install。 - 中文缺字：构建前会自动执行 kai_gen_gothic 字体安装步骤，留意该步骤是否报错即可。
五种格式、一条命令，这本书以后想怎么读，就怎么读。
【免费下载链接】progit2-zh项目地址: https://gitcode.com/gh_mirrors/pr/progit2-zh
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
