用 Gitbook 打造 Gitbook教程

Gitbook是一个出色的开源平台，可以通过简单的markdown文件生成精美的文档documentation和书籍e-books。
他们也有带编辑的付费版本，但是，免费的开源版本可以轻松地通过与插件集成使用，满足绝大部分使用者的需要。

GitBook是什么

官方给的定义：

GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc).

GitBook 是基于 Node.js 的开源命令行工具，用于输出漂亮的电子书。

GitBook 支持 Markdown 和 AsciiDoc 两种语法格式，能够输出 html，pdf，epub，mobi等多种格式。

Modern book format and toolchain using Git and Markdown

GitBook 特性

• Markdown 或 AsciiDoc 语法
• 多类型支持：网站(html)或电子书 (pdf, epub, mobi)
• 多语言
• 目录、大纲
• 封面
• 模板和变量
• 模板继承
• 插件
• 主题

为何出这个文档

作为一个技术宅，经常性的写一些文档，或使用说明，由于很早就接触了博客系统，因此一直使用 markdown 来编写文档。

时间长了，资料越来越多，也越来越乱，它们经常散落在某个角落，内容不系统化，也不方便管理。于是希望有一个工具解决这个问题，然后就找到了 GitBook。诚然，它不是最好的解决方案，很多博客系统提供了专栏功能，很多编辑器如有道云笔记都能通过 markdown 来管理自己的文档。但是它们都不够纯粹，我只希望将自己分散的 markdown 文件组织起来，形成类似一本书，就这个需求来看，GitBook 最符合我的需要。

接下来的内容，都是关于 GitBook 的使用，和 gitbook.com 没有啥关联，如果你希望通过 gitbook.com 来托管你的书籍，可以移步 GitBook.com

为了能更好地阐释 GitBook，我通过 GitBook 生成了一本电子书，来讲述 如何玩转 GitBook

主要内容：

• 安装 GitBook
• GitBook 基本配置
• 高频常用插件
• GitBook 主题
• GitBook 导出pdf

缺陷

开源项目停止维护

活跃的开源项目，意味着不断完善的功能，不断修复bug，及时的反馈，更多社区的帮助…

遗憾的是，GitBook开源项目已经停止维护，专注打造的 gitbook.com 网站在国内访问受限。

移动端适配性不好

现在有PC端的流量已经赶不上移动端了，但是 GitBook 对移动设备的支持不太友好。

虽然正文部分做到了 responsive，但是整体很粗糙(包括设计方案和显示细节)。

很多插件也没有考虑移动端的情形。

常见主题演示

Gitbook api theme 主题演示

一般用于API 的展示，不同语言对同一解决方案的展示，Gitbook API 演示

Gitbook default theme 主题演示

Gitbook 默认的显示效果，黑白风格，简约、正式。绝大多数Gitbook 自动生成的电子书都是这个风格，查看演示

Gitbook comscore theme 主题演示

利用 Gitbook comscore 主题改变了 书的风格，包含完整版的 gitbook 教程，所有最新的内容都在此版本，链接直达

Gitbook faq theme 主题演示

借助 gitbook faq 主题开发的帮助中心，类似与很多网站的帮助中心，问答平台等，查看效果