1 背景

Modern book format and toolchain using Git and Markdown
使用 Git 和 Markdown 来编排书籍

2安装

安装nodejs
npm安装gitbook
npm install gitbook -g
离线编辑器
haroopad可以实时显示格式化后的输出效果

image.png

3使用

gitbook 的基本用法非常简单：初始化+编译

3.1 使用 gitbook init 初始化书籍目录

$ tree book/
book/
├── README.md
└── SUMMARY.md

windows系统目录结构
（_book是格式化后的html文件）

F:\mybook\msgIntroduction-20200519 的目录
020/05/19  14:32    <DIR>          chapter1
020/05/19  14:32    <DIR>          chapter2
020/05/20  09:17    <DIR>          chapter3
020/05/19  14:32    <DIR>          chapter4
020/05/19  15:06               406 README.md
020/05/20  10:21               693 SUMMARY.md
020/05/20  10:02    <DIR>          _book

README.md
对书籍的介绍

$ cat book/README.md 
# README

This is a book powered by [GitBook](https://github.com/GitbookIO/gitbook).

SUMMARY.md

$ cat book/SUMMARY.md 
# SUMMARY

* [Chapter1](chapter1/README.md)
  * [Section1.1](chapter1/section1.1.md)
  * [Section1.2](chapter1/section1.2.md)
* [Chapter2](chapter2/README.md)

创建了这两个文件后，使用 gitbook init，它会为我们创建 SUMMARY.md 中的目录结构。

$ cd book
$ gitbook init
$ tree
├── README.md
├── SUMMARY.md
├── chapter1
│   ├── README.md
│   ├── section1.1.md
│   └── section1.2.md
└── chapter2
    └── README.md

3.2 使用 gitbook serve 编译书籍

书籍目录结构创建完成后，使用 gitbook serve 编译和预览书籍。
该命令实际上会首先调用 gitbook build 编译书籍，完成以后会打开一个 web 服务器，监听在本地的 4000 端口。gitbook serve --port XXXX

linux

$ gitbook serve
Press CTRL+C to quit ...

Live reload server started on port: 35729
Starting build ...
Successfully built!

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

windows

F:\mybook\msgIntroduction-20200519>gitbook se
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 14 pages
info: found 22 asset files
info: >> generation finished with success in

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

image.png

3.4 创建自己的web站点

安装nginx，然后把html文件放到nginx/html目录下，这样就有自己的web站点了。如下图所示：

image.png

附录一 nodejs安装

1）官网下载，并安装
node -v 查看版本

2）设置国内镜像
npm config set registry http://registry.npm.taobao.org

3）全局安装gitbook
npm install gitbook-cli -g
gitbook -v 查看安装的版本

附录二 gitbook命令大全

gitbook init //初始化目录文件
gitbook help //列出gitbook所有的命令
gitbook --help //输出gitbook-cli的帮助信息
gitbook build //生成静态网页
gitbook serve //生成静态网页并运行服务器
gitbook build --gitbook=2.0.1 //生成时指定gitbook的版本, 本地没有会先下载
gitbook ls //列出本地所有的gitbook版本
gitbook ls-remote //列出远程可用的gitbook版本
gitbook fetch 标签/版本号 //安装对应的gitbook版本
gitbook update //更新到gitbook的最新版本
gitbook uninstall 2.0.1 //卸载对应的gitbook版本
gitbook build --log=debug //指定log的级别
gitbook builid --debug //输出错误信息