D 的个人博客

全职做开源,自由职业者

  menu

使用 GitBook 写文档

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

GitBook 简介

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

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

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

Git 方式

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

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

正所谓:“人法地,地法天,天法道,道法自然”啊。

Markdown

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

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

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

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

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

静态站点

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

客户端编辑器

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

GitBook Editor

其他

GitBook 还有很多功能,例如:

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

题外话

GitHub、GitBook、GitXXX 都很流行啊,为什么呢?

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