Zander's blog

Welcome To Zander's Blog

0%

带你入坑gitbook

基于应用场景介绍Gitbook

1.需求场景

最开始正常都是手写的笔记,但是有一些问题,不方便带,不方便共享,字不好看的还不想看,更改麻烦,当然也有一些优点,比如回忆很强,速度相对比较快。

所以后来有了电子版的,如微软的OneNote和word,以及一些在线笔记、博客等等,这些笔记都有一个特点,富文本编辑,即写完一个字或者写完一句话再调格式,这就是富文本,富文本使用简单,且用户已有长期的使用习惯,但是也存在一定的问题,不同版本之间样式差别,以及复杂的环境安装。

所以推荐使用Markdown,文字和样式一起“写”,比如# 简介就表示标题一,标题名为简介,你甚至可以直接用记事本书写,现在几乎任何平台都支持Markdown,你可以写完源码发布在其他平台,他的源码也非常清楚明了,个人认为可以将markdown理解为HTML的简化版本,数据的本质就是你怎么看,怎么解释,怎么渲染而已。关于markdown的更多介绍,你可以在https://zlogs.net/learn-markdown/进行初步学习,当然现在各大平台也都有简要介绍,和详细语法说明。

上面推荐了使用markdown记笔记,很多零散的事情或者知识点可以通过博客等发表,或者本地记录,关于博客的搭建需求,稍后更新,但是更多场景下是很多知识都具有系统性,比如学习一门编程语言,如果记载一个markdown文件,不仅大,而且不易查询,解决方法是拆分成几个markdown文件,通过一个文件向目录一样写下前后顺序,好的问题解决了,但是还有一个问题,每次查看内容,都需要先查看目录,再查看内容,有点麻烦,不如像word实现一个大纲导航,懒是科技第一推动力,gitbook就是解决这样问题的,像gitbook一样的在线或者离线,闭源或者开源软件还有很多,本文暂时不做展开,下面的【2】就是介绍在本地使用gitbook。

Gibook本地使用

上面介绍了gitbook生成pdf等其他文件,但是我想支持渲染公式,或者自定义样式,gitbook的插件可以解决。

Gitbook插件系统

上面推荐使用gitbook,还有一个问题,电子版笔记的优点之一便于共享,gitbook也有这样的优点,gitbook可以根据.md源码生成html以及其他文件,还能本地预览,当然,如果本地是云主机的话就实现远端浏览了,如果没有云主机可以使用现在的github等的pages服务。

Gitbook在线pages

上面已经介绍了推送到pages实现远端浏览,要是能够每次写完源码直接推送到云端,让他自己解释就好了,Github+Action就可以解决这样问题,每次推送远端源码,自动生成html页面,推送到pages。

Gitbook自动集成

发现推送到github pages的百度不收录,要是可以直接推送到多个pages平台实现同步就好了,action也能解决。

Gitbook百度收录

不想让别人看见源码,只是看见pages,action也可以解决。

Gitbook源码隐藏与私有库使用

2.Gitbook本地使用

根据上面的需求,如果自己开发这样一款软件需要实现怎样的逻辑,首先必须有目录,而且只能有一个目录,然后必须有正文,至少有一页正文,然后必须有翻译软件,即Gitbook CLI,实现将目录和正文翻译成一个东西的程序。

2.1 Gitbook CLI安装

本地安装要求

安装GitBook既简单又直接。您的系统只需要满足以下两个要求:

  • NodeJS(建议使用v4.0.0及更高版本)
  • Windows,Linux,Unix或Mac OS X

2.1.1下载安装nodejs

地址为https://nodejs.org/zh-cn/

2.1.2 下载安装gitbook CLI

window

  • 任意目录运行cmd
  • 输入npm install gitbook-cli -g

linux

  • 输入npm install gitbook-cli -g

2.2 创建目录正文

2.2.1使用下列命令

1
gitbook init

将创建一个SUMMARY.mdREADME.md文件

2.2.2下面介绍一下目录的语法

目录名必须为SUMMARY.md

目录内容为

1
2
3
4
5
6
7
8
# Summary

* [本书简介](README.md)
* [速查](page/1010.md)
* [简介](page/1011.md)
* [发展](page/1012.md)
* [原理](page/1147.md)
* [配置](page/1013.md)
1
*空格[标题文字](相对路径)

最终效果如下:

注意:

1.目录可以有缩进

即上面的发展、原理和配置

2.目录结构可以为## 加字符产生类似于开发中不可点击的效果

1
2
3
4
5
6
7
8
9
10
# Summary

* [本书简介](README.md)
* [速查](page/1010.md)
* [简介](page/1011.md)
* [发展](page/1012.md)
* [原理](page/1147.md)
* [配置](page/1013.md)

## 测试

3.目录结构可以为---分割线,产生划分效果

1
2
3
4
5
6
7
8
9
10
11
# Summary

* [本书简介](README.md)
* [速查](page/1010.md)
---
* [简介](page/1011.md)
* [发展](page/1012.md)
* [原理](page/1147.md)
* [配置](page/1013.md)

## 测试

2.3 浏览效果

2.3.1 预览

使用以下方法预览和提供图书:

1
gitbook serve

打开浏览器,输入http://localhost:4000

即可看到效果

2.3.2 构建静态网站

或使用以下方法构建静态网站:

1
gitbook build

_book目录里面生成的就是静态html文件

2.3.3 生成pdf和电子书

下列三个命令分别生成pdf和电子书

1
2
3
gitbook pdf
gitbook epub
gitbook mobi

3.Gitbook插件系统

根据需求场景支持渲染公式,或者自定义样式下面介绍一下插件系统,

如果让我们来设计这样一个软件,如果表示新加一个插件呢,加在正文里面不合适,加在目录里面不合适,不如新添加一个文件专门来表示有哪些插件或者配置,book.json就是这样的一个文件

主要由三部分构成

1
2
3
{大括号
属性名:属性
}
1
2
3
4
5
其中的title表示这本书的标题,作者、描述同理
语言标记本书语言
gitbook可以后面跟着版本
links后面你可以自己自定义目录显示其他外链
插件介绍可以翻到文末,每次添加完插件需要,gitbook install安装插件

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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
{
"title": "Zander's Book",
"author": "Zander Zhao",
"description": "My Learn Book",
"language": "zh-hans",
"gitbook": "3.2.3",
"links": {
"sidebar": {
"总目录": "https://zlogs.net/learn-page"
}
},
"plugins": [
"pageview-count",
"mygitalk",
"github",
"github-buttons",
"include-csv",
"page-toc-button",
"local-video",
"3-ba",
"chart",
"ga",
"graph",
"mermaid-gb3",
"puml",
"mermaid",
"katex",
"quiz",
"accordion",
"click-reveal",
"auto-scroll-table",
"alerts",
"donate",
"klipse",
"todo",
"hide-element",
"chapter-fold",
"code",
"splitter",
"advanced-emoji",
"emphasize",
"-lunr",
"-search",
"search-pro",
"sectionx",
"tbfed-pagefooter",
"popup",
"todo",
"-sharing",
"sharing-plus"
],
"pluginsConfig": {
"github-buttons": {
"buttons": [
{
"user": "ZanderZhao",
"repo": "learn-c",
"type": "star",
"width": "60",
"size": "small"
},
{
"user": "zanderzhao",
"type": "follow",
"width": "60",
"count": true,
"size": "small"
}
]
},
"github": {
"url": "https://github.com/ZanderZhao"
},
"mygitalk": {
"clientID": "364365cexxxxxxxxx",
"clientSecret": "447ef6648e9dfffe2exxxxxxxxxxxxxxxxx",
"repo": "talk",
"owner": "zanderzhao",
"admin": [
"zanderzhao"
],
"distractionFreeMode": false
},
"page-toc-button": {
"maxTocDepth": 2,
"minTocSize": 2
},
"ga": {
"token": "UA-149127400-1"
},
"quiz": {
"labels": {
"showCorrect": "显示正确答案",
"check": "确认",
"showExplanation": "查看解释",
"explanationHeader": "Explanation"
},
"text": {
"noChosen": "",
"incomplete": ""
},
"buttons": {
"showCorrect": true,
"showExplanation": true
}
},
"3-ba": {
"token": "6bb7c6072673exxxxxxxxxxxxxxxxx"
},
"chart": {
"type": "c3"
},
"donate": {
"wechat": "https://raw.githubusercontent.com/ZanderZhao/images/master/mypay/book/wechat.jpg",
"alipay": "https://raw.githubusercontent.com/ZanderZhao/images/master/mypay/book/alipay.jpg",
"title": "",
"button": "赏",
"alipayText": "支付宝打赏",
"wechatText": "微信打赏"
},
"hide-element": {
"elements": [
".gitbook-link"
]
},
"tbfed-pagefooter": {
"copyright": "转载注明出处 &copy Zander Zhao",
"modify_label": "该文章修订时间:",
"modify_format": "YYYY-MM-DD HH:mm:ss"
},
"sharing": {
"all": [
"linkedin",
"qq",
"weibo",
"facebook",
"twitter",
"qzone",
"douban",
"instapaper",
"google",
"messenger",
"viber",
"whatsapp"
]
}
}
}

效果如下:

4.Gitbook在线pages

上面2.3.2已经介绍了生成静态网页,下面介绍将该网页部署到github的pages上

本质就是把生成的html文件发在github pages上

1.新建项目

2.项目名字,设为公共,初始化,创建

3.新建gh-pages分支

4.在gh-pages上传文件

5.将_book文件夹下的文件全部上传到gh-pages,可以直接拖拽,也可以点上传

6.设置里面翻到底下点那个地址访问

5.Gitbook自动集成

你可以直接使用https://github.com/ZanderZhao/gitbook-action

使用说明见https://ZanderZhao.github.io/gitbook-action

6.注意

gitbook开源项目地址在https://github.com/GitbookIO/gitbook,但是官方好像不维护了,

可以搜索https://www.npmjs.com/search?q=gitbook-plugin寻找

部分插件介绍可以在:https://gitbook-org.github.io/gitbook-zhangjikai/plugins.html寻找,

本文旨在带你入坑,没有具体展开,而且现在已有许多非常详细的介绍,比如上面链接的,

我建了一个组织https://github.com/gitbook-org我将以前使用gitbook时的一些介绍项目整合在里面

后期也将加入更多插件,期待你的加入

7.参考