Markdown+gitbook编写帮助文档

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 - converters ：https://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