GitBook 你人生的第一本书

GitBook ,你人生的第一本书

做笔记写文档非常凌乱，不好管理，于是寻找各种文档工具

docsify (https://docsify.js.org/#/zh-cn/)

  • docsify不是静态生成html，而通过动态请求markdown编译生成html**。

  • docsify还具有轻应用、全文搜索功能、支持多个主题、兼容IE10+、支持SSR等特性

Gitbook

  • 简洁（采用Markdown语法，没有其他渲染，符合记录学习笔记的定位）
  • 可在线浏览、可转成电子书（PDF、ePub、Mobi）
  • 形成工具使用体系（Git、GitHub、GitHub Pages、GitBook）
  • 不怕编写失误（每次提交记录都可追溯）

Phenomic

hexo

  • Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown（或其他渲染引擎）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。有高扩展性、静态的特性。

下面介绍gitbook

最好的教程是官方文档 https://docs.gitbook.com/
以下只是个人笔记，如有疏漏，请多包涵。更新中……

1.准备工作

安装 Node.js
GitBook 是一个基于 Node.js 的命令行工具，下载安装 Node.js （https://nodejs.org/en)
安装完成之后，有如下提示。

This package has installed:
• Node.js v10.16.3 to /usr/local/bin/node
• npm v6.9.0 to /usr/local/bin/npm
Make sure that /usr/local/bin is in your $PATH.

你可以使用下面的命令来检验是否安装成功。

1
2
3
4
5
$ node -v
v10.16.3

npm -v
6.9.0

2.安装Gitbook命令

1
sudo npm install -g gitbook-cli

检查是否安装成功

1
2
3
4
gitbook -V

CLI version: 2.3.2
GitBook version: 3.2.3

3.GitBook 初体验

新建一本书的目录gitbook(此名称随便起)，进入gitbook目录，创造一本书。

1
2
3
4
5
6
7
8
$ mkdir gitbook
$ cd mybook
$ 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 这两个文件，README.md 应该不陌生，就是说明文档，而 SUMMARY.md 其实就是书的章节目录。

接下来，我们输入 命令，然后在浏览器地址栏中输入 http://localhost:4000 便可预览书籍。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
$ gitbook serve

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.3s ! 

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

CTRL+Z 强制退出后再启动，遇到的问题

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
gitbook serve

... Uhoh. Got error listen EADDRINUSE: address already in use :::35729 ...
Error: listen EADDRINUSE: address already in use :::35729
    at Server.setupListenHandle [as _listen2] (net.js:1270:14)
    at listenInCluster (net.js:1318:12)
    at Server.listen (net.js:1405:7)
    at Server.listen (/private/var/root/.gitbook/versions/3.2.3/node_modules/tiny-lr/lib/server.js:164:15)
    at Promise.apply (/private/var/root/.gitbook/versions/3.2.3/node_modules/q/q.js:1165:26)
    at Promise.promise.promiseDispatch (/private/var/root/.gitbook/versions/3.2.3/node_modules/q/q.js:788:41)
    at /private/var/root/.gitbook/versions/3.2.3/node_modules/q/q.js:1391:14
    at runSingle (/private/var/root/.gitbook/versions/3.2.3/node_modules/q/q.js:137:13)
    at flush (/private/var/root/.gitbook/versions/3.2.3/node_modules/q/q.js:125:13)
    at process._tickCallback (internal/process/next_tick.js:61:11)

You already have a server listening on 35729
You should stop it and try again.

解决办法

1
kill -9 $(lsof -t -i:35729)

4.详细介绍下 GitBook 目录结构及相关文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
sh-3.2# tree
.
├── README.md
├── SUMMARY.md
└── _book
    ├── gitbook
    │   ├── fonts
    │   │   └── fontawesome
    │   │       ├── FontAwesome.otf
    │   │       ├── fontawesome-webfont.eot
    │   │       ├── fontawesome-webfont.svg
    │   │       ├── fontawesome-webfont.ttf
    │   │       ├── fontawesome-webfont.woff
    │   │       └── fontawesome-webfont.woff2
    │   ├── gitbook-plugin-fontsettings
    │   │   ├── fontsettings.js
    │   │   └── website.css
    │   ├── gitbook-plugin-highlight
    │   │   ├── ebook.css
    │   │   └── website.css
    │   ├── gitbook-plugin-livereload
    │   │   └── plugin.js
    │   ├── gitbook-plugin-lunr
    │   │   ├── lunr.min.js
    │   │   └── search-lunr.js
    │   ├── gitbook-plugin-search
    │   │   ├── lunr.min.js
    │   │   ├── search-engine.js
    │   │   ├── search.css
    │   │   └── search.js
    │   ├── gitbook-plugin-sharing
    │   │   └── buttons.js
    │   ├── gitbook.js
    │   ├── images
    │   │   ├── apple-touch-icon-precomposed-152.png
    │   │   └── favicon.ico
    │   ├── style.css
    │   └── theme.js
    ├── index.html
    └── search_index.json

README.md
书本简介内容

1
2
# 序言
 >人生的第一本电纸书

SUMMARY.md
这个文件主要决定 GitBook 的章节目录，它通过 Markdown 中的列表语法来表示文件的父子关系

1
2
3
4
5
6
7
8
9
10
11
# Summary
  
* [序言](README.md)

* [第一章](chapter1/README.md)
    * [第一节](chapter1/seciont1.md)
    * [第二节](chapter1/section2.md)
* [第二章](chapter2/README.md)
    * [第一节](chapter2/seciont1.md)
    * [第二节](chapter2/section2.md)
* [结束](end/README.md)

fonts字体文件夹
images图片文件夹

插件文件夹
gitbook-plugin-fontsettings
gitbook-plugin-highlight
gitbook-plugin-livereload
gitbook-plugin-lunr
gitbook-plugin-search
gitbook-plugin-sharing

GitBook 有插件官网，默认带有 5 个插件，highlight、search、sharing、font-settings、livereload。

5.帮助文档

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
sh-3.2# gitbook

  Usage: gitbook [options] [command]


  Options:

    -v, --gitbook [version]  specify GitBook version to use
    -d, --debug              enable verbose error
    -V, --version            Display running versions of gitbook and gitbook-cli
    -h, --help               output usage information


  Commands:

    ls                        List versions installed locally
    current                   Display currently activated version
    ls-remote                 List remote versions available for install
    fetch [version]           Download and install a <version>
    alias [folder] [version]  Set an alias named <version> pointing to <folder>
    uninstall [version]       Uninstall a version
    update [tag]              Update to the latest version of GitBook
    help                      List commands for GitBook
    *                         run a command with a specific gitbook  version

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
sh-3.2# gitbook help
    build [book] [output]       build a book
        --log                   Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
        --format                Format to build to (Default is website; Values are website, json, ebook)
        --[no-]timing           Print timing debug information (Default is false)

    serve [book] [output]       serve the book as a website for testing
        --port                  Port for server to listen on (Default is 4000)
        --lrport                Port for livereload server to listen on (Default is 35729)
        --[no-]watch            Enable file watcher and live reloading (Default is true)
        --[no-]live             Enable live reloading (Default is true)
        --[no-]open             Enable opening book in browser (Default is false)
        --browser               Specify browser for opening book (Default is )
        --log                   Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
        --format                Format to build to (Default is website; Values are website, json, ebook)

    install [book]              install all plugins dependencies
        --log                   Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

    parse [book]                parse and print debug information about a book
        --log                   Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

    init [book]                 setup and create files for chapters
        --log                   Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

    pdf [book] [output]         build a book into an ebook file
        --log                   Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

    epub [book] [output]        build a book into an ebook file
        --log                   Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

    mobi [book] [output]        build a book into an ebook file
        --log                   Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
软件工具
#Gitbook
GitBook 你人生的第一本书
http://www.keker.top/2019/08/27/tools/gitbook/
作者
Keker
发布于
2019年8月27日
许可协议