基于Markdown + gitbook编写高逼格的文档

2019-10-24 21:13发布

站内文章 / 后端开发

44 0

够拽才男人

女 | 书童

私信

一、简介

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

支持输出多种文档格式：

- 静态站点：GitBook 默认输出该种格式，生成的静态站点可直接托管搭建 Github Pages 服务上；

- PDF：需要安装 gitbook-pdf 依赖；

- eBook：需要安装 ebook-convert；

- 单HTML网页：支持将内容输出为单页的HTML，不过一般用在将电子书格式转换为PDF或eBook的中间过程；

- JSON：一般用于电子书的调试或元数据提取；

使用 GitBook 制作电子书，必备两个文件：*README.md* 和 *SUMMARY.md*

二、GitBook 准备工作

2.1 系统环境

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

2.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

2.3 安装 Node.js 和 npm

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

shell> yum -y install nodejs npm
shell> node -v
v6.17.1
shell> npm -v
3.10.10

# 由于不可说的原因，npm install 时速度总是非常慢，用如下方式修改npm源
shell> npm config set registry https://registry.npm.taobao.org
# 查看修改结果
shell> npm config get registry

2.4 安装 GitBook

shell> npm install gitbook-cli -g

# 验证安装结果
shell> gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3

三、创建 Gitbook 账号与配置

3.1 创建GitBook账号的过程这里不再说明，根据官方注册内容填写。注册网址：https://app.gitbook.com/join

3.2 登录GitBook页面 https://app.gitbook.com/login

3.3 创建一个项目

按照步骤点击"Create a new space"后，在弹出的窗口中输入项目名称，然后点击"Create"创建新的项目，这里我们以91donkey为例创建一个Public权限的空间：

3.4 项目初始界面，这个时候我们就可以在界面右侧进行内容编写了。

3.5 设置GitBook to GitHub功能支持

点击左侧"盒子"的图标，然后启用"GitHub"，根据弹出的界面配置GitHub的同步地址，配置完成后，在GitBook上保存的内容，会自动同步到GitHub上。

四、Linux环境配置（作为Client端撰写Markdown文档时配置）

4.1 初始化

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

shell> mkdir /home/gitbook/
shell> cd /home/gitbook/
shell> gitbook init
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished

- README.md：书的介绍文字，如前言、简介，在章节中也可做为章节的简介。

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

4.2 启动服务

默认Web界面端口4000
shell> gitbook serve /home/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.6s ! 
Starting server ...
Serving book on http://localhost:4000

4.3 用浏览器访问 http://localhost:4000 预览电子书效果