使用GitBook进行知识整理

Posted by locus on 2019-10-27

一、安装使用gitbook

1、安装gitbook

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

1
2
$ node -v
v12.1.0

安装Gitbook

1
2
npm install gitbook-cli -g
# 验证是否安装成功

二、Gitbook文件目录介绍

gitbook 的使用可以简单的归纳为如下两步：

使用 gitbook init 初始化书籍目录
使用 gitbook build 编译书籍到静态网站
使用 gitbook serve 本地访问书籍

在使用 gitbook init 之后本地会生成两个文件 README.md 和 SUMMARY.md ，这两个文件都是必须的，一个为本书介绍，一个为本书目录结构。

1、初始化项目

新建文件

1
gitbook init

2、启动服务

1
2
gitbook serve   //也可以直接输入gitbook serve ./ docs
// 直接访问localhost:4000

运行该命令后会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件，我们可以使用下面命令来生成网页而不开启服务器。

3、目录结构

使用gitbook init 后会自动生成两个文件 README 和 SUMMARY

  • README.md使用过git的都知道这个文件
  • SUMMARY.md就是自己要写文章章节目录

简单看下我最基本的目录

1
2
3
4
5
6
7
8
9
10
.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

三、Gitbook book.json配置文件

1、book.json

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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
{
  "title": "标题",
  "author": "作者",
  "description": "简单描素",
  "language": "zh-hans", 
  "gitbook": "3.2.3", 
  "styles": {
    "website": "./styles/website.css" 
  },
  "structure": {
    "readme": "README.md" 
  },
  "links": {
    "sidebar": {
      "我的博客": "https://blog.csdn.net/xxx" 
    }
  },
  "plugins": [ 
    "-sharing",
    "splitter",
    "expandable-chapters-small",
    "anchors",

    "github",
    "github-buttons",
    "donate",
    "sharing-plus",
    "anchor-navigation-ex",
    "favicon"
  ],
  "pluginsConfig": {
    "github": {
      "url": "https://github.com/xxx/"
    },
    "github-buttons": {
      "buttons": [{
        "user": "kuangshp",
        "repo": "mysql",
        "type": "star",
        "size": "small",
        "count": true
      }]
    },
    "donate": {
      "alipay": "./source/images/donate.png",
      "title": "",
      "button": "赞赏",
      "alipayText": " "
    },
    "sharing": {
      "douban": false,
      "facebook": false,
      "google": false,
      "hatenaBookmark": false,
      "instapaper": false,
      "line": false,
      "linkedin": false,
      "messenger": false,
      "pocket": false,
      "qq": false,
      "qzone": false,
      "stumbleupon": false,
      "twitter": false,
      "viber": false,
      "vk": false,
      "weibo": false,
      "whatsapp": false,
      "all": [
        "google", "facebook", "weibo", "twitter",
        "qq", "qzone", "linkedin", "pocket"
      ]
    },
    "anchor-navigation-ex": {
      "showLevel": false
    },
    "favicon": {
      "shortcut": "./source/images/favicon.jpg",
      "bookmark": "./source/images/favicon.jpg",
      "appleTouch": "./source/images/apple-touch-icon.jpg",
      "appleTouchMore": {
        "120x120": "./source/images/apple-touch-icon.jpg",
        "180x180": "./source/images/apple-touch-icon.jpg"
      }
    }
  }
}

关于book.json字段的介绍

  • title: 书籍标题
  • author:书籍作者
  • description: 描述
  • language:语言
  • gitbook:gitbook的版本
  • styles:自定义样式
  • structure: readme文件的位置
  • links:链接跳转
  • plugins:插件
  • pluginsConfig:插件的配置

2、SUMMARY

这个文件主要决定 GitBook 的章节目录，它通过 Markdown 中的列表语法来表示文件的父子关系，下面是一个简单的示例：

1
2
3
4
5
6
7
8
9
# Summary

* [Introduction](README.md)
* [Part I](part1/README.md)
    * [Writing is nice](part1/writing.md)
    * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
    * [We love feedback](part2/feedback_please.md)
    * [Better tools for authors](part2/better_tools.md)

我们通过使用 标题 或者 水平分割线 将 GitBook 分为几个不同的部分，如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Summary

### Part I

* [Introduction](README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)

### Part II

* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)

---

* [Last part without title](part3/title.md)

3、插件

GitBook 有 插件官网，默认带有 5 个插件，highlight、search、sharing、font-settings、livereload，如果要去除自带的插件， 可以在插件名称前面加 -，比如：

1
2
3
"plugins": [
    "-search"
]

如果要配置使用的插件可以在 book.json 文件中加入即可，比如我们添加 plugin-github，我们在 book.json 中加入配置如下即可：

1
2
3
4
5
6
7
8
{
    "plugins": [ "github" ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/your/repo"
        }
    }
}

然后在终端输入 gitbook install ./ 即可。

三、Gitbook书籍发布

gitbook书籍生成

gitbook生成书籍有两种方式，一种是使用gitbook serve命令生成本地预览，另外一种方式是使用gitbook build来生成相应页面

1
2
3
4
gitbook serve //本地会生成_book目录的文件夹
gitbook build
gitbook serve ./ docs   //把本地预览生成文件存储在 docs目录下
gitbook build ./ docs

Git push上传至github

1
2
3
git add -A
git commit -m "some update"
git push origin master



FEATURED TAGS
FRIENDS