Pro Git 2 多格式电子书一键构建完全指南：HTML、PDF、EPUB 全搞定

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，或者干脆打印成纸质书。下面带你从零走通整个流程。

📖 先看看成品长什么样

构建完成后，仓库根目录会多出五个文件，各管各的阅读场景：

书稿里穿插了大量手绘风格的示意图，转换进上述格式后依然清晰可读：

🔧 倒推回去：先把 Ruby 环境装好

整个构建基于 Ruby + Rake，准备阶段只有两步：

git clone https://gitcode.com/gh_mirrors/pr/progit2-zh cd progit2-zh bundle install

bundle 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"，耐心等即可。

如果只想要某一种格式，直接调用对应子任务就行：

📚 生成完成之后：怎么用、怎么改

• 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