GitBook 是一个基于 Node.js 的命令行工具,可使用 Github/Git 和 Markdown 来制作精美的电子书,

GitBook 支持输出多种文档格式:

1)静态站点:GitBook 默认输出该种格式,生成的静态站点可直接托管搭建 Github Pages 服务上;

2)PDF:需要安装 gitbook-pdf 依赖;

3)eBook:需要安装 ebook-convert;

4)单HTML网页:支持将内容输出为单页的HTML,不过一般用在将电子书格式转换为PDF或eBook的中间过程;

5)JSON:一般用于电子书的调试或元数据提取;

使用 GitBook 制作电子书,必备两个文件:*README.md* *SUMMARY.md*

 

gitbook 官网:https://www.gitbook.com

gitbook 价格:https://www.gitbook.com/pricing

gitbook docs:https://docs.gitbook.com

gitbook 示例:https://github.com/GitbookIO/gitbook/blob/master/docs/examples.md

 

 

GitBook 安装

1、系统环境

需要准备一台CentOS 7.5 x86_64系统环境,用于部署gitbook服务器端程序,用于在本地查看gitbook编辑保存的内容。

 

2、修改yum源可跳过,若安装不成功,可考虑国内阿里云的源站)

shell> wget -O /etc/yum.repos.d/CentOS-Base.repo http://mirrors.aliyun.com/repo/Centos-7.repo
shell> wget -O /etc/yum.repos.d/epel.repo http://mirrors.aliyun.com/repo/epel-7.repo
shell> yum clean all
shell> yum makecache

 

3、安装 Node.js 和 npm

GitBook 是一个基于 Node.js 的命令行工具,下载安装 Node.js,安装完成之后,你可以使用下面的命令来检验是否安装成功。

# yum -y install nodejs npm
。。。。。。

# node -v
v6.17.1
# npm -v
3.10.10

注:由于某墙的原因,若 npm install 时速度总是非常慢,用如下方式修改npm源 (可跳过

npm config set registry https://registry.npm.taobao.org

查看修改npm源的结果

npm config get registry

 

4、安装 GitBook

npm install gitbook-cli -g

# npm install gitbook-cli -g
/usr/bin/gitbook -> /usr/lib/node_modules/gitbook-cli/bin/gitbook.js
/usr/lib
└── gitbook-cli@2.3.2 

 

5、查看安装版本号

gitbook -V

# gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
gitbook@3.2.3 ../../tmp/tmp-509zfDMsbs1jq4I/node_modules/gitbook
├── bash-color@0.0.4
├── escape-html@1.0.3
├── escape-string-regexp@1.0.5
├── ignore@3.1.2

。。。。。。

urce-inliner@2.0.0)
GitBook version: 3.2.3

 

 

Gitbook 账号创建与配置

1、创建 GitBook 账号

注册网址:https://app.gitbook.com/join  (因为某些原因,很慢,或无法登陆)

直接用 github(推荐,后面会发布到github) 或 谷歌账号授权注册

过程这里不再说明,根据官方注册内容填写。

 

2、登录 GitBook 页面

网址:https://app.gitbook.com/join  (因为某些原因,很慢,或无法登陆)

直接用 github(推荐,后面会发布到github) 或 谷歌账号授权登录

 

3、创建一个项目

按照步骤点击"Create a new space"后,在弹出的窗口中输入项目名称,例如:mimvp-proxy-doc

然后,可见选择公开 Public,点击"Create"创建新的项目,如下图:

上面,是以用户名 GangYang 登录 gitbook,并创建一个Public权限的空间 mimvp-proxy-doc

 

4、项目初始界面

这个时候我们就可以在界面右侧进行内容编写了

 

5、设置GitBook to GitHub功能支持

点击左侧"盒子"的集成"Integrations"图标,然后启用"GitHub",

根据弹出的界面配置GitHub的同步地址,配置完成后,在GitBook上保存的内容,会自动同步到GitHub上。

 

 

Linux 环境配置(作为Client端撰写Markdown文档时配置)

1、初始化

创建一个文件夹,使用 gitbook init 对其初始化,会自动生成两个必要的文件 *README.md* 和 *SUMMARY.md*

# mkdir /root/git/gitbook/
# cd /root/git/gitbook/
# gitbook init
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished 
#
# ll
-rw-r--r-- 1 root root 16 Dec 21 22:33 README.md
-rw-r--r-- 1 root root 40 Dec 21 22:33 SUMMARY.md

1)README.md:书的介绍文字,如前言、简介,在章节中也可做为章节的简介。

2)SUMMARY.md 定制书籍的章节结构和顺序。

 

2、启动服务

默认Web界面端口4000 

# gitbook serve /root/git/gitbook/
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.9s ! 

Starting server ...
Serving book on http://localhost:4000

 

3、用浏览器访问

默认是在本地搭建访问:http://localhost:4000 

注意:若您在服务器上(非本机)搭建的 gitbook,访问地址:http://your_server_ip:4000  ,例如:http://118.24.184.177:4000

预览电子书效果,如下图:

 

4、注意事项

由于在每次重启 gitbook serve 服务的时候,_book 目录下的文件都会被清空,

# tree -L 3 /root/git/gitbook/
/root/.gitbook/gitbook/
├── _book
│   ├── gitbook
│   │   ├── fonts
│   │   ├── gitbook.js
│   │   ├── gitbook-plugin-fontsettings
│   │   ├── gitbook-plugin-highlight
│   │   ├── gitbook-plugin-livereload
│   │   ├── gitbook-plugin-lunr
│   │   ├── gitbook-plugin-search
│   │   ├── gitbook-plugin-sharing
│   │   ├── images
│   │   ├── style.css
│   │   └── theme.js
│   ├── index.html
│   └── search_index.json
├── README.md
└── SUMMARY.md

10 directories, 7 files

为避免资料的丢失 _book,应将md文件转换为html文件,放在nginx下访问,这样也就不用启动gitbook服务了

 

 

 

 

 

 

 

如何实现一个类似阿里云/腾讯云的产品帮助文档系统

Github 是如何使用 Github 来处理 Github 文档的

github  pages https://pages.github.com

jekyllrb plugins - convertershttps://jekyllrb.com/docs/plugins/#converters

aws 文档惯例https://docs.aws.amazon.com/zh_cn/general/latest/gr/docconventions.html

qcloud-documents, 腾讯云官方文档 使用Makrdown自动构建

 

语雀 - 项目文档:https://www.yuque.com

 

 

互联网大公司的帮助文档

阿里云文档

帮助文档:https://help.aliyun.com/document_detail/108490.html

Github:https://github.com/AlibabaCloudDocs/ecs

 

腾讯云文档

帮助文档:https://cloud.tencent.com/document/product/213/15691

Github:https://github.com/tencentyun/qcloud-documents

 

百度云文档

帮助文档:https://cloud.baidu.com/doc/BCC/s/kjy6wob04

Github:

 

华为云文档

帮助文档:https://support.huaweicloud.com/api-ecs/zh-cn_topic_0093055772.html

Github:https://github.com/huaweicloudDocs (github 托管目录,跟阿里云一样

 

网易云文档

帮助文档:https://www.163yun.com/help/documents/68487242478440448

Github:

 

AWS 文档

帮助文档:https://docs.aws.amazon.com/zh_cn/AWSEC2/latest/APIReference/API_AllocateAddress.html

Github:

AWS 文档底部(API_AllocateAddress_SeeAlso),有代码示例,非常人性化

 

 Google Cloud 文档

帮助文档:https://cloud.google.com/compute/docs/reference/rest/v1/acceleratorTypes/list

Github:

Google Cloud 比 AWS 文档更加人性化:

1)右侧,试试看,可以直接调试API接口,立即看到结果

2)底部,代码示例,直接查看多种编程语言,不用跳转(AWS需要跳转一次,到集中地代码示例查看)

 

以上,花费了大量精力调研帮助文档,发现真是一门技术与艺术,做到人性化文档,还是要下一番苦功夫滴!

米扑代理的帮助文档:https://proxy.mimvp.com/doc

 

 

参考推荐:

几款制作帮助文档的工具汇总

Markdown + gitbook编写高逼格的文档

GitBook 使用教程