Mr丶冷文

文章 分类 评论
115 10 5698

站点介绍

冷文学习者(KEVINLU98.COM),记录一个北漂小码农的日常业余生活
友链申请地址(直接评论即可): 传送门

Gitbook+码云创建自己的文档

MR丶冷文 2021-11-22 914 4条评论 网站相关 giteegitbook

首页 / 正文
Freewind主题v1.5版本已发布,下载请移步Freewind 1.5,同时还有主题伴生插件Freewind Markdown,下载请移步 Freewind Markdown,有问题请在留言板,交换友链请直接在友链留言,我创建了一个主题交流群,有兴趣可以加下: 点此加入
报毒我说明一下,是因为我把主题的版权信息做了加密,其中用了eval,杀毒软件认为eval函数是一个危险的操作,这点介意的话请勿下载,我也没有强迫任何人去下载,也没有向大家收取一分钱的主题费用,所以也犯不着因为这些事情来喷我,喜欢就用,不喜欢就不用,就这么简单

发布于2022-10-28

前言

之前Freewind的主题使用手册是在看云上写的,后来觉得在看云不方便更新,刚好因为改动比较大,大部分文档需要重新写,就索性直接换成gitbook,我在网上也搜了一下gitbook+码云,但是没找到相关资料,就自己整理一下给大家分享,先看看成品

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/22eb5966afb248c8965fc461cb5c3394.png

Q:为什么要用码云来部署Gitbook?

A:因为想要你的在线文档任何人都能通过URL访问到,就得将其部署上线,当然我们可以将它当做静态网站部署到服务器上,但是那样难免会有服务器成本且更新起来不方便,而码云的Gitee Pages与github的Pages都可以帮助我们发布静态页面,但由于Github因内访问起来比较慢,就选择了码云

准备工作

安装NodeJs

安装gitbook所需组件gitbook-cli,当然它需要依赖node.js来运行,我们可以直接在NodeJs官网去下载nodejs然后安装

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/72541a1fcb984c249dd9f82abafc833d.png

我这里介绍另外一种方法,用nvm(nodejs version management)来安装,它是nodejs的版本管理工具,通过它可以安装和切换不同版本的nodejs。

https://github.com/nvm-sh/nvm这是nvm的github仓库,大家可以参考里面的说明来安装,我自己是Mac OS的系统,我下面就以我自己的环境为例安装

直接执行如下脚本进行安装

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.39.0/install.sh | bash

安装完成之后输入nvm -v来验证,如果安装成功打输出nvm的版本

➜  ~ nvm -v
0.39.0

我们可以使用nvm install 版本号来安装不同版本的node.js,我在Mac OS下安装大于10的版本使用Gitbook会报错,应该是XCode有些地方没有配置好,所以我这里就安装10.24的版本

➜  ~ nvm install 10
Downloading and installing node v10.24.1...
Downloading https://nodejs.org/dist/v10.24.1/node-v10.24.1-darwin-x64.tar.xz...
###################################################################################################################################################################################### 100.0%
Computing checksum with shasum -a 256
Checksums matched!
Now using node v10.24.1 (npm v6.14.12)
Creating default alias: default -> 10 (-> v10.24.1)

我们可以通过nvm list来列出安装的nodejs版本,而箭头指向的就是我们当前使用的版本,也可以通过nvm use 版本号来切换

➜  ~ nvm list
->     v10.24.1
default -> 10 (-> v10.24.1)
iojs -> N/A (default)
unstable -> N/A (default)
node -> stable (-> v10.24.1) (default)
stable -> 10.24 (-> v10.24.1) (default)
lts/* -> lts/gallium (-> N/A)
lts/argon -> v4.9.1 (-> N/A)
lts/boron -> v6.17.1 (-> N/A)
lts/carbon -> v8.17.0 (-> N/A)
lts/dubnium -> v10.24.1
lts/erbium -> v12.22.7 (-> N/A)
lts/fermium -> v14.18.1 (-> N/A)
lts/gallium -> v16.13.0 (-> N/A)
➜  ~ nvm use 10
Now using node v10.24.1 (npm v6.14.12)

我们安装完nodejs之后可以运行node -v来查看nodejs的版本

➜  ~ node -v
v10.24.1

安装gitbook-cli

安装了nodejs,我们也就有了npm(node package management),接下来我们直接使用npm去安装gitbook-cli

npm install -g gitbook-cli # -g表示全局安装

运行gitbook -V(大写),如果输出版本号则安装成功

➜  ~ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

本地使用

编写文档

创建一个目录,然后进入目录运行gitbook init来初始化

➜  book mkdir testbook
➜  book cd testbook
➜  testbook gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
➜  testbook

可以用例如vs code等工具打开

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/0b056f327a254583b15490926ffcfbd8.png

比如我们要写一如下结构的文档

介绍
前言
第一章
    第1.1节
    第1.2节
第二章
    第2.1节
    第2.2节
后记

我们修改我们的SUMMARY.md文件,这个文件是我们文档的目录,其实说白是就是一个markdown文档

# Summary

* [介绍](README.md)
* [前言](preface.md)
* [第一章]()
    * [第1.1节](part1/section1_1.md)
    * [第1.2节](part1/section1_2.md)
* [第二章]()
    * [第1.1节](part2/section2_1.md)
    * [第1.2节](part2/section2_2.md)
* [后记](postscript.md)

然后我们创建对应的文件就可以啦,我们看看目录结构

➜  testbook tree
.
├── README.md
├── SUMMARY.md
├── part1
│   ├── section1_1.md
│   └── section1_2.md
├── part2
│   ├── section2_1.md
│   └── section2_2.md
├── postscript.md
└── preface.md

2 directories, 8 files

我们在part1/section1_1.md中写入如下内容

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/b73efa6b78e440eda087e4c3cf0d08c2.png

构建文档

接下来使用gitbook build来构建我们的页面

➜  testbook gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
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 3 pages
info: found 4 asset files
info: >> generation finished with success in 0.4s !

接下来我们可以看到在我们的目录下多了一个_book的目录,里面有字体,css文件,js脚本,html文件,我们不难发现html文件和我们之前创建的markdown文件是对应上的,其实就是Gitbook帮我们将我们的markdown文件翻译成了html页面

➜  testbook 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-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
│   ├── part1
│   │   ├── section1_1.md
│   │   └── section1_2.md
│   ├── part2
│   │   ├── section2_1.md
│   │   └── section2_2.md
│   ├── postscript.html
│   ├── preface.html
│   └── search_index.json
├── part1
│   ├── section1_1.md
│   └── section1_2.md
├── part2
│   ├── section2_1.md
│   └── section2_2.md
├── postscript.md
└── preface.md

14 directories, 38 files

本地运行

使用gitbook serve来启动一个服务器,其实就是把_book映射到了网站的根目录,接下来访问http://localhost:4000即可

➜  testbook 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 3 pages
info: found 4 asset files
info: >> generation finished with success in 0.5s !

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

点到第1.1小节,看到如下内容

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/c572ec772b8c496b9f733ba9a472beab.png

接下来我们只需要给每个文件中写入内容再次重新生成即可

码云部署

初始化本地仓库

我们将我们的文档项目使用git init初始化为一个git项目

➜  testbook git init
Initialized empty Git repository in /Users/lengwen/Code/book/testbook/.git/
➜  testbook git:(master) ✗

然后使用如下命令提交变更

➜  testbook git:(master) ✗ git add -A
➜  testbook git:(master) ✗ git commit -m "初始化完成"
[master (root-commit) 168c95e] 初始化完成
 39 files changed, 3117 insertions(+)
 create mode 100644 README.md
 create mode 100644 SUMMARY.md
 create mode 100644 _book/gitbook/fonts/fontawesome/FontAwesome.otf
 create mode 100644 _book/gitbook/fonts/fontawesome/fontawesome-webfont.eot
 create mode 100644 _book/gitbook/fonts/fontawesome/fontawesome-webfont.svg
 create mode 100644 _book/gitbook/fonts/fontawesome/fontawesome-webfont.ttf
 create mode 100644 _book/gitbook/fonts/fontawesome/fontawesome-webfont.woff
 create mode 100644 _book/gitbook/fonts/fontawesome/fontawesome-webfont.woff2
 create mode 100644 _book/gitbook/gitbook-plugin-fontsettings/fontsettings.js
 create mode 100644 _book/gitbook/gitbook-plugin-fontsettings/website.css
 create mode 100644 _book/gitbook/gitbook-plugin-highlight/ebook.css
 create mode 100644 _book/gitbook/gitbook-plugin-highlight/website.css
 create mode 100644 _book/gitbook/gitbook-plugin-livereload/plugin.js
 create mode 100644 _book/gitbook/gitbook-plugin-lunr/lunr.min.js
 create mode 100644 _book/gitbook/gitbook-plugin-lunr/search-lunr.js
 create mode 100644 _book/gitbook/gitbook-plugin-search/lunr.min.js
 create mode 100644 _book/gitbook/gitbook-plugin-search/search-engine.js
 create mode 100644 _book/gitbook/gitbook-plugin-search/search.css
 create mode 100644 _book/gitbook/gitbook-plugin-search/search.js
 create mode 100644 _book/gitbook/gitbook-plugin-sharing/buttons.js
 create mode 100644 _book/gitbook/gitbook.js
 create mode 100644 _book/gitbook/images/apple-touch-icon-precomposed-152.png
 create mode 100644 _book/gitbook/images/favicon.ico
 create mode 100644 _book/gitbook/style.css
 create mode 100644 _book/gitbook/theme.js
 create mode 100644 _book/index.html
 create mode 100644 _book/part1/section1_1.md
 create mode 100644 _book/part1/section1_2.md
 create mode 100644 _book/part2/section2_1.md
 create mode 100644 _book/part2/section2_2.md
 create mode 100644 _book/postscript.html
 create mode 100644 _book/preface.html
 create mode 100644 _book/search_index.json
 create mode 100644 part1/section1_1.md
 create mode 100644 part1/section1_2.md
 create mode 100644 part2/section2_1.md
 create mode 100644 part2/section2_2.md
 create mode 100644 postscript.md
 create mode 100644 preface.md

远程仓库

在码云上新建一个仓库,一定要勾选开源

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/9fa9f68020fa4243b5d67f58930ec7a7.png

创建成功

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/0b65121dd8c845fabab12a7b143bac6b.png

接下来关联远程仓库与本地仓库

使用如下命令

git remote add origin git@gitee.com:kevinlu98/booktest.git  # 后面是你自己的远程仓库地址

使用如下命令推送本地变更到远程仓库

git push origin master

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/92d1c882067b47369bee019532563870.png

再次来到远程仓库我们可以看到已经和本地仓库同步了

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/36a68de92ef9486fbaf2be3311770910.png

开启Gitee Pages

在仓库点 服务-> Gitee Pages

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/adfbb1aef65f4ba1b51f0b947559472c.png

部署我们的_book目录为网站根目录即可,因为我们知道Gitbook实际就是把我们markdown翻译成了html页面放到了_book目录

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/9dd675819dae46619be6368ebf05ee9a.png

部署成功后我们直接访问码云返回给我们的链接即可

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/2ec5f4053d444abe88dfc94cd1ba2def.png

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/b4d45af65a8240d9ad03cd06ae40375c.png

更新

我们下次要更新文档怎么办呢?我们现在在本地做如下变更

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/72856b8dd8f1481d9974ddf2a6f6cefc.png

我们重新构建一下Gitbook

➜  testbook git:(master) ✗ gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
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 7 pages
info: found 0 asset files
info: >> generation finished with success in 0.7s !

我们变更完成之后再次提交变更

➜  testbook git:(master) ✗ git status
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   _book/index.html
    modified:   _book/part1/section1_1.html
    modified:   _book/part1/section1_2.html
    modified:   _book/part2/section2_1.html
    modified:   _book/part2/section2_2.html
    modified:   _book/postscript.html
    modified:   _book/preface.html
    modified:   _book/search_index.json
    modified:   part1/section1_1.md

no changes added to commit (use "git add" and/or "git commit -a")
➜  testbook git:(master) ✗ git add -A
➜  testbook git:(master) ✗ git commit -m "1.1小节更新"
[master f305b6d] 1.1小节更新
 9 files changed, 10 insertions(+), 10 deletions(-)
➜  testbook git:(master)

然后使用git push origin master推送变更到远程仓库

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/1f50cb6c75874523856a8ea4dc2a519a.png

可以看到我们远程仓库已经更新了

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/b420b1d7f34f43db9f9f55acc866571b.png

我们再次来到Gitee Pages,点击更新

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/b8ac7c8da91c42f584fc00f5f2d94985.png

更新成功

https://imagebed-1252410096.cos.ap-nanjing.myqcloud.com/2054/2b2c6e557a424034a0615daba321bc3d.png

评论(4)

  1. 常瑞 游客 2021-12-27 21:01 回复

    大佬可以看看gitbook

    1. MR丶冷文 管理员 2021-12-27 21:31 回复

      @常瑞

      各有各的好处吧,自己搭建可以自定义很多东西,插件之类的

    2. 常瑞 游客 2021-12-27 21:05 回复

      @MR丶冷文

      哦哦,https://www.gitbook.com 官方这个不是很方便?

    3. MR丶冷文 管理员 2021-12-27 21:02 回复

      @常瑞

      我就是用gitbook部署的呀,只是自已去部署gitbook

最新评论

  •  hh

  •  hh

  • 蝌蚪

    支持大佬

  • SURELY

    下载支持一下大佬

  • SURELY

    大佬支持啊,下载了试一下

日历

2022年12月

    123
45678910
11121314151617
18192021222324
25262728293031

文章目录

站点公告
Freewind主题v1.5版本已发布,下载请移步Freewind 1.5,同时还有主题伴生插件Freewind Markdown,下载请移步 Freewind Markdown,有问题请在留言板,交换友链请直接在友链留言,我创建了一个主题交流群,有兴趣可以加下: 点此加入
报毒我说明一下,是因为我把主题的版权信息做了加密,其中用了eval,杀毒软件认为eval函数是一个危险的操作,这点介意的话请勿下载,我也没有强迫任何人去下载,也没有向大家收取一分钱的主题费用,所以也犯不着因为这些事情来喷我,喜欢就用,不喜欢就不用,就这么简单
点击小铃铛关闭