Gitbook搭建环境 Gitbook搭建环境

Gitbook搭建环境准备工作 1. 安装Node.js
【Gitbook搭建环境】Gitbook是基于Node.js的命令行工具，需要下载Node.js才能使用。当安装完成后，可以使用如下命令测试是否安装成功。

$ node -v v12.12.0

2. 安装Gitbook
输入下面命令安装Gitbook

npm install gitbook-cli -g

当安装完成后，可以使用如下命令测试是否安装成功。

$ gitbook -V CLI version: 2.3.2 GitBook version: 3.2.3

3. 安装Git
这个不用细说，和远程相关联时要用到。下载地址。
当安装完成后，可以使用如下命令测试是否安装成功。

git --version git version 2.23.0

上面三个都安装完成后，正常运行的界面。

文章图片
image 本地Gitbook 初步搭建环境
当准备工作做好后，使用Gitbook的命令相当简单。如果想要创建一个简单的书籍，只需要在需要的文件夹下输入gitbook init命令，便可以得到如下输出。

warn: no summary file in this book info: create README.md info: create SUMMARY.md info: initialization is finished

如果想要预览书籍的话，在命令行中输入gitbook serve后，根据提示在浏览器中输入http://localhost:4000就可以预览书籍了。
当输入gitbook serve后，会在文件夹下创建一个_book文件夹，里面有生成网页的相关html文件，并且开启服务器，便可以在浏览器中预览书籍。
预览效果如下图所示。

文章图片
image
如果只想生成_book文件夹，但是不开启服务器，只需要执行gitbook build就可以了。
配置Gitbook
当执行完git init后，就会在对应的文件夹下面创建README.md和SUMMARY.md两个文件。SUMMARY.md是整个书的目录，README.md是本书的说明文档。然而只是用默认的两个文件是一般是不能满足我们的使用要求的。所以需要自定义书籍结构。
如果需要进一步扩展Gitbook中的相关的功能，就需要配置目录结构。一般在对应的文件目录结构如下。

. ├── book.json ├── README.md ├── SUMMARY.md ├── chapter-1/ |├── README.md |└── something.md └── chapter-2/ ├── README.md └── something.md

其中和书籍结构相关的文件有book.json和SUMMARY.md，其中book.json用于存放书籍的相关配置信息，SUMMARY.md是整个书的目录。其他的文件都是和书籍的内容相关的，每个章节下的README.md文件是对本章节的描述，而整个书的README.md是对整个书籍的描述。下面针对book.json和SUMMARY.md分别进行介绍。
book.json配置文件 book.json文件用于配置Gitbook书籍的相关选项，现在将我的book.json文件内容放出来。

{ "title": "我的gitbook", "author": "jackymxp", "description": "测试Gitbook", "language": "zh-hans", "gitbook": "3.2.3", "styles": { "website": "./styles/website.css" }, "structure": { "readme": "README.md" }, "links": { "sharing": { "all": null, "facebook": null, "google": null, "twitter": null, "weibo": null }, "sidebar": { "码不能停": "https://jackymxp.github.io/" } }, "plugins": [ "-sharing", "splitter", "expandable-chapters-small", "anchors", "github", "github-buttons", "donate", "sharing-plus", "anchor-navigation-ex", ], "pluginsConfig": { "github": { "url": "https://github.com/jackymxp" }, "donate": { "alipay": "", "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 } } }

对json文件中的参数做一下介绍：

参数	描述	备注
`title`	本书标题
`autor`	本书作者
`description`	本书描述
`language`	本书语言	zh-hans
`gitbook`	指定的gitbook版本
`styles`	自定义页面样式
`structure`	指定 Readme、Summary、Glossary 和 Languages 对应的文件名
`links`	在左侧导航栏添加链接信息
`plugins`	配置使用的插件
`pluginsConfig`	配置插件的属性

有关插件的内容，下面会具体讲。
SUMMARY.md目录文件 SUMMARY.md文件的作用是配置文章的目录结构，是根据Markdown中的列表相关语法来表示不同层级的目录关系。下面是一个简单的示例。
当书籍的目录结构如下所示时：

. ├── 1-chapter │├─1-part │├─2-part │└─README.md ├── 2-chapter │├─1-part │├─2-part │└─README.md ├── README.md ├── SUMMARY.md └── book.json

此时应该更改SUMMARY.md文件如下所示。

# Summary* [Introduction](README.md)# 对应本书的描述* [第一章](1-chapter/README.md)# 对应本章节的描述 * [第一节](1-chapter/1-part.md) * [第二节](1-chapter/2-part.md)* [第二章](2-chapter/README.md)# 对应本章节的描述 * [第三节](2-chapter/1-part.md) * [第四节](2-chapter/2-part.md)

当执行gitbook serve后的预览效果。

文章图片
image
插件
Gitbook默认自带5个插件，包括highlight、search、sharing、font-settings、livereload，如果需要更多的插件，可以访问插件官网。
插件的配置如果我们想要使用某个插件，只需要在book.json中添加即可使用，例如想要添加plugin-github插件，只需要在book.json中更改配置如下所示：

{ "plugins": [ "github" ], "pluginsConfig": { "github": { "url": "https://github.com/your/repo" } } }

如果我们不想使用自带的插件，只需要在插件名前面加-即可。例如我们不想使用search插件，只需要按照如下配置即可。

"plugins": [ "-search" ]

当在book.json中添加了相关的插件后，在预览或者编译之前需要进行安装相关插件，执行gitbook install来实现插件安装。当安装完插件后，会创建node_modules文件夹
与远程相关联 master分支如果需要将书籍发布到Github上，可以按照步骤进行发布。
首先建立一个仓库，在仓库中存在两个分支，一个管理书籍本身，也就是本地内容；另外一个分支存放html文件用于发布。
在假设有GitHub账号的前提下，新建一个仓库。

文章图片
image 将其下载到本地。

文章图片
image 首先，在提交之前写好.gitignore文件是明智的，由于在master分支中不需要跟踪_book中的内容和插件文件夹node_modules下的相关文件，除此之外还有一些和操作系统的相关文件，都不需要跟踪。写好的.gitignore文件如下。

# gitbook 相关文件 # _book node_modules # OS generated files # ###################### .DS_Store* ehthumbs.db Icon? Thumbs.db *.icloud# Prerequisites *.d# Compiled Object files *.slo *.lo *.o *.obj# Precompiled Headers *.gch *.pch# Compiled Dynamic libraries *.so *.dylib *.dll# Fortran module files *.mod *.smod# Compiled Static libraries *.lai *.la *.a *.lib# Executables *.exe *.out *.app

将写好的.gitignore执行git add和git commit -m””，即可生效。
然后，将写好的书籍文件移动到test-gitbook文件夹下，此时执行git status如下图所示。

文章图片
image 使用git add、git commit -m"first commit”、git push将其提交到远程仓库即可。

文章图片
image 到此，我们的内容便可以实时进行跟踪了。接下来需要将书籍内容发布到网页上。
gh-pages分支在本地新建一个分支，在这个分支中只存放发布的html文件，也就是_book文件夹下对应的内容。
使用git checkout -b gh-pages新建并切换到gh-pages分支上，使用命令ls | grep -v _book | xargs rm -rf删除该文件夹下除了_book文件夹外的所有文件，并且将_book下的文件全部移动到上一层目录，然后删除_book文件夹。

ls | grep -v _book| xargs rm -rf; mv ./_book/* ./ rm -rf _book

此时，当前目录下的文件结构如下图所示。

文章图片
image 最后使用git add .、git commit -m"first depoy”和git push --set-upstream origin gh-pages将带有html文件内容上传到远程。

文章图片
image 最后选择setting按钮，在里面找到GitHub Pages选项，点击网址，即可打开新的网页，看到书籍内容。

文章图片
image

文章图片
image 为了方便发布，将上述过程写成一个脚本。

#!/bin/bash touch .gitignoreecho " run.sh # gitbook 相关文件 # _book node_modules # OS generated files # ###################### .DS_Store* ehthumbs.db Icon? Thumbs.db *.icloud# Prerequisites *.d# Compiled Object files *.slo *.lo *.o *.obj# Precompiled Headers *.gch *.pch# Compiled Dynamic libraries *.so *.dylib *.dll# Fortran module files *.mod *.smod# Compiled Static libraries *.lai *.la *.a *.lib# Executables *.exe *.out *.app" > .gitignore# 增加到git git add .gitignore git commit --amend# 安装插件，发布 gitbook init gitbook install gitbook build#gitbook serve# 推送到远程 git add . git commit -m"first commit" git push -f# 准备发布 mv ./_book /tmp/git branch -D gh-pages git checkout -b gh-pages ls | xargs rm -rf mv /tmp/_book ./ mv ./_book/* ./ rm -rf _bookgit add . git commit -m"first depoy" git push -f--set-upstream origin gh-pagesgit checkout master

有了这个脚本，当编写完书籍后，可以运行sh run.sh便可以自动的发布到GitHub Pages上面了。