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
腾讯云文档
帮助文档：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
参考推荐：
版权所有: 本文系米扑博客原创、转载、摘录，或修订后发表，最后更新于 2020-02-19 05:25:06
侵权处理: 本个人博客，不盈利，若侵犯了您的作品权，请联系博主删除，莫恶意，索钱财，感谢！