Gitbook的安装和使用

title: Gitbook的安装和使用 id: 7745d54f4f807978e82ab79f9a8665be tags: [] date: 2000/01/01 00:00:00 updated: 2023/03/04 19:29:12 isPublic: true --#|[分隔]|#--

Gitbook的安装和使用

gitbook是非常适合开发和展示书籍、文档类前端网站项目的工具，开发时使用markdown语法，编译后展示的页面自带目录、清晰明了。

现在这个网站就是使用gitbook开发的，是边研究边开发完成后，过了一段时间要添加文档时，才发现gitbook的一些命令有些遗忘，才注意到也应该给他写一个文档，这才有了此文。

这里所讲的，是本地使用搭建gitbook环境、gitbook指令使用、项目开发、实时查看项目效果、打包等方面的说明，不涉及markdown文档开发、线上部署或使用github配置的环节。

这是博客园一个gitbook插件汇总，可能会是高频使用点，放在上面，GitBook插件整理 - book.json配置

所有指令

这里先放一下所有指令，方便以后看。

npm install -g gitbook-cli：全局安装gitbook gitbook -V：查看 gitbook 版本 gitbook init：初始化gitbook项目 gitbook serve：本地启动gitbook服务 gitbook install：安装插件 gitbook build：构建gitbook项目

前置准备

gitbook是基于node的应用，所以需要先搭建node环境，这里只说明一下：本地无论是windows还是Mac，都可以直接去node官网下载安装包进行安装，仅简单。

node安装完成，就可以使用node的自带指令，进行gitbook的安装和使用了。

注意

官方已经不再维护了gitbook工具了，所以gitbook已经不能支持版本比较的node和npm，现在已知的能够支持的node版本：v12.18.2，npm版本：6.14.5。

如果是先安装的其他版本的node或npm，安装gitbook报错失败，那切换node版本前，需要先把gitbook卸载，否则会有缓存。

gitbook 的安装

注意，一个系统只用安装一次

使用npm进行全局安装：npm install -g gitbook-cli

当上面指令跑完后，可以查看一下gitbook版本

gitbook -V

# 正常应该输出下面，但如果只输入第一行，第二行开始打转，那说明是只安装了gitbook-cli，现在开始正常安装gitbook了，安装完成后会可以再次查看
CLI version: 2.3.2
GitBook version: 3.2.3

后面就可以使用gitbook init或者gitbook install等指令了：

这里也有修改gitbook版本的方法：

# 卸载3.23版本的gitbook
gitbook uninstall 3.2.3

# 安装其他版本的gitbook，这里安装3.2.2版本
gitbook fetch 3.2.2

# 再次查看当前gitbook版本
gitbook -V

# 输出
CLI version: 2.3.2
GitBook version: 3.2.2

下面我的一个gitbook项目所需的版本，其他版本搭配不确定能不能用，但下面这个是可以的(有的版本卡在gitbook install，有的版本卡在gitbook serve)

# node
v11.11.0

# npm
6.7.0

# gitbook
CLI version: 2.3.2
GitBook version: 3.2.2

gitbook 的使用

查看 gitbook 版本：gitbook -V

初始化 gitbook

进入一个空的文件夹，在控制台的当前文件夹目录下执行gitbook init，会自动生成两个文件。

• SUMMARY.md：gitbook主要目录，所有的md格式的文档，都需要这里写一下目录，后面编译时才会把那个md格式文档转为正常的网页文件格式。

• README.md：自动生成的第一个文档。

启动服务，进行开发

在控制台执行gitbook serve，会启动gitbook服务，自动对项目进行编译，自动生成一个名为_book的临时文件夹，并打印：

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 20 plugins are installed 
info: 14 explicitly listed 
【一些其他提示】
info: found 12 pages 
info: found 132 asset files 
use simple mode:  true
info: >> generation finished with success in 1.7s ! 

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

此时可以在浏览器中，打开提示中的http://localhost:4000路径，即可看到当前的项目。

如果此时修改了md文件中的内容，控制台会自动跑一跑，然后页面会自动刷新，新改动的内容即体现在页面上。

这里的_book文件夹就是构建生成的网页文件。

如果需要停止，则需要用键盘按下 control + c 即可。

gitbook配置文件book.json

新建book.json文件，里面主要是这些内容：(里面的注释是我后加的，真实使用时不能有注释)

{
  "title" : "Gitbook Use", // 设置书本的标题
  "author" : "zhangjikai", // 作者的相关信息
  "description" : "记录Gitbook的配置和一些插件的使用", // 本书的简单描述
  // Gitbook使用的语言, 版本2.6.4中可选的语言如下：
  // en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw
  "language" : "zh-hans",
  "links" : { // 在左侧导航栏添加链接信息
    "sidebar" : {
      "Home" : "http://zhangjikai.com"
    }
  },
  // 使用的一些插件
  // Gitbook默认带有5个插件: [highlight search sharing font-settings livereload]
  // 如果要去除自带的插件， 可以在插件名称前面加 '-'
  "plugins": [
    "-search",
    "atoc"
  ],
  "pluginsConfig": { // 插件的配置
    "theme-default": {
      "showLevel": true
    }
  },
  "styles": { // 单独引用一些css样式文件
    "website": "./assets/styles/website.css"
  }
}

其中book.json不是必须的，里面的每一项也不是必须的，自己酌情使用即可。

gitbook项目的插件，主要是用来调整文档样式，或者给gitbook修改添加一些功能的，插件很多，这里不再一一列举，需要什么功能可以直接网上搜索一下，很可能就有实现这个功能的插件。

插件是需要安装，只用插件的名字写在book.json中，然后控制台执行gitbook install，就会生成node_modules文件夹，里面就是所有用到的插件。

需要注意的是，node_modules只有在开发和构建时有用，部署项目时不需要这个文件夹。

下面把我这个项目的文件内容贴一下，有需自取，当前日期是2020.05.17，以后如果配置变了，这里可能不会同步吆~

{
  "title": "鸟语",
  "language": "zh-hans",
  "styles": {
    "website": "./assets/styles/website.css"
  },
  "plugins": [
    "-lunr", 
    "-search", 
    "-sharing",
    "-font-settings",
    "search-pro",
    "expandable-chapters-small",
    "code",
    "theme-api",
    "hide-element",
    "back-to-top-button",
    "logo",
    "splitter",
    "favicon-absolute",
    "atoc",
    "3-ba",
    "popup"
  ],
  "pluginsConfig": {
    "hide-element": {
      "elements": [".gitbook-link"]
    },
    "logo": {
      "logo": "",
      "title": "",
      "url": ""
    },
    "favicon-absolute": {
      "favicon": "./assets/images/favicon.ico",
      "appleTouchIconPrecomposed152": "./assets/images/apple-touch-icon.png"
    },
    "atoc": {
      "addClass": true,
      "className": "toc"
    },
    "3-ba": {
      "token": "我个人的token，就不放了"
    }
  }
}

打包项目

当文档开发完毕后，停止服务，在控制台输入指令gitbook build，就能进行构建，会在生成_book文件夹，里面就是可用的前端项目，里面有这个项目所有需要的资源。

这个_book和开发时的_book文件夹，貌似没啥不一样。。。最后还是再使用构建指令全新构建一下，盖棺定论一下。

然后就可以_book中的前端项目，部署到线上即可。