使用 GitBook 写文档的教程

最近发现很多技术书籍都放在 GitBook 上提供给人们阅读，刚好 Wide 也需要写文档，索性就尝试使用 GitBook 来做。

GitBook 是一个通过 Git 和 Markdown 来撰写书籍的工具，最终可以生成 3 种格式：

• 静态站点 ：包含了交互功能（例如搜索、书签）的站点
• PDF ：PDF 格式的文件
• eBook ：ePub 格式的电子书文件
  

GitBook 是免费且开源的，项目地址： https://github.com/GitbookIO/gitbook

GitBook 使用 Git 进行写作内容管理。

• 从用户的角度看，这样能够方便地进行多人协作（连程序源代码都能管好，书籍自然不在话下），还不用学习额外概念或用法
• 从设计实现的角度看，这样能够合理利用已有工具（不重复造轮）满足产品需求，甚至扩展性更好（Git 相关服务能够利用的太多了）
  

正所谓：“人发地，地法天，天法道，道法自然”啊。

GitBook 不只是利用了 Git，目前非常流行的 Markdown 也被运用其中。

使用 Markdown 最大的好处就是简单：

• 语法简单，并且能够形象地表达出意图（例如无序列表使用 * ，强调使用 ** ，一个 # 表示 H1、两个 # 表示 H2）
• 不干扰写作者：语法标记在视觉上对写作者的负面影响不大（不像 HTML 满屏的 <>）
• 
  

总之，Markdown 就是能够让写作者更专注于内容创作。

不过 GitBook 不只是简单地使用 Markdown，使用 Markdown 编写的内容只是源格式，最终的目标格式可以为 PDF、ePub 等。

在本地编写完内容后我们需要将内容提交到 GitBook 上进行书籍的构建。GitBook 会将书籍构建为 4 种格式（JSON、ePub、PDF、Website）。 其中我们最常用的应该是静态站点，这样能够方便传播。

可以使用 GitBook 的官方编辑器来进行写作、发布等管理，非常方便：

GitBook 还有很多功能，例如：

• 自定义静态站点域名
• 多语言支持
• 书籍私有
• 自定义封面（弄个漂亮的书皮吧）
• 交互式练习、提问（这个用于写问答类书籍或习题类书籍会很有用）
  

GitHub、GitBook、GitXXX 都很流行啊，为什么呢？

Git 已经不只是一个版本控制系统了，它的分布式协作方式正在潜移默化地影响着很多程序的设计，最终影响了很多在线服务的提供方式。这样一种 私有-公有 可控的网络信息架构是非常值得我们学习并实践的，这样架构的各类产品将越来越多。

原文  http://88250.b3log.org/write-doc-via-gitbook