用 Gitbook 打造 Gitbook教程

清疚 2023-07-09 06:23 25阅读 0赞

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

![在这里插入图片描述][20200228093229107.png_pic_center]

## 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 主题
 *  GitBook 导出pdf

### 缺陷 ###

#### 开源项目停止维护 ####

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

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

#### 移动端适配性不好 ####

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

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

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

## 常见主题演示 ##

##### Gitbook api theme 主题演示 #####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA_size_16_color_FFFFFF_t_70]  
一般用于API 的展示，不同语言对同一解决方案的展示，[Gitbook API 演示][Gitbook API]

##### Gitbook default theme 主题演示 #####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA_size_16_color_FFFFFF_t_70 1]

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

##### Gitbook comscore theme 主题演示 #####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA_size_16_color_FFFFFF_t_70 2]  
利用 Gitbook comscore 主题改变了 书的风格，包含完整版的 gitbook 教程，所有最新的内容都在此版本，[链接直达][GitBook]

## Gitbook faq theme 主题演示 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA_size_16_color_FFFFFF_t_70 3]  
借助 gitbook faq 主题开发的帮助中心，类似与很多网站的帮助中心，问答平台等，[查看效果][Link 2]

[20200228093229107.png_pic_center]: https://img-blog.csdnimg.cn/20200228093229107.png#pic_center
[GitBook.com]: https://www.gitbook.com/
[GitBook]: https://www.mapull.com/gitbook/comscore/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200228092800237.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA==,size_16,color_FFFFFF,t_70
[Gitbook API]: https://www.mapull.com/gitbook/api/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200228092823273.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA==,size_16,color_FFFFFF,t_70
[Link 1]: https://www.mapull.com/gitbook/default/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200228092835151.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20200228092846826.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2ppYW5nY2hhbzg1OA==,size_16,color_FFFFFF,t_70
[Link 2]: https://www.mapull.com/gitbook/faq/