个人gitbook在线文档搭建

一、安装

  目前最新官网的命令为：npm install @gitbook/cli -g，但GitBook 集成平台目前处于 alpha 阶段。它尚未向开发人员开放，并且要求node的最低版本为node 18.x。

所以使用原先的gitbook方式

1、node版本

  原先的gitbook-cli安装有版本限制，据网上说Node 版本 10.23.0 以下版本可使用。

  但使用nvm list available发现，像10.22.0这样的老旧版本是铁定没有的，所以要手动去官网下载

https://nodejs.org/en/download/releases/

  在官网下载并解压10.22.0版本文件，并将其放到nvm安装路径下手动新建的v10.22.0文件夹中。

# 1、切换node版本
nvm list
nvm use 10.22.0 # 管理员身份下打开cmd才生效

# 2、更换npm镜像
npm config get registry
npm config set registry https://registry.npm.taobao.org/

2、gitbook-cli安装

npm install -g gitbook-cli
gitbook -V

说明：后面可能会出现下面的警告信息（不要理会即可）

二、gitbook使用

  前面安装好后，下面进入gitbook项目创建阶段

创建一个项目文件夹，并进入到该文件夹中，执行后面命令

1、初始化

gitbook init

SUMMARY.md是目录文档， REAMDE.md是项目内容

2、项目使用

①SUMMARY.md文件

SUMMARY.md 的格式是一个简单的链接列表，链接的名字是章节的名字，链接的指向是章节文件的路径。

• 示例

# 概要

- [第一章](part1/README.md)
  - [1.1 第一节](part1/writing.md)
  - [1.2 第二节](part1/gitbook.md)
- [第二章](part2/README.md)
  - [2.1 第一节](part2/feedback_please.md)
  - [2.2 第二节](part2/better_tools.md)

② 项目化

npm init

  然后修改新增的package.json文件（新增内容如下）：

{
  "scripts": {
    "serve": "gitbook serve",
    "build": "gitbook build"
  },
}

③ 启动打包项目

• 启动项目

npm run serve

• 打包项目

npm run build

三、其他

1、.bookignore

  和 Git 一样， Gitbook 会依次读取 .gitignore, .bookignore 和 .ignore 文件来将一些文件和目录排除。

package.json
package-lock.json
.bookignore

2、book.js

module.exports = {
  title: 'Gitbook电子书',
  author: 'lencamo',
  lang: 'zh-cn',
  description: 'Gitbook电子书示例项目',
};

3、插件

• 自己选择性安装

# 隐藏元素
npm install pluginName

# 搜索内容高亮
npm install gitbook-plugin-search-pro

# 代码框优化
npm install gitbook-plugin-code

# 返回顶部
npm install gitbook-plugin-back-to-top-button

# 菜单栏折叠
npm install gitbook-plugin-expandable-chapters

# 主题(例如：gitbook-plugin-theme-lou)
npm install gitbook-plugin-theme-主题名

• 配置book.js

module.exports = {
  plugins: [
    "hide-element",
    "-lunr",
    "-search",
    "search-pro",
    "code",
    "back-to-top-button",
    "expandable-chapters",
  ],
  pluginsConfig: {
    "hide-element": {
      elements: [".gitbook-link"],
    },
  },
};

三、说明

参考文献 ：https://songlu-cube.gitee.io/courseware-gitbook-demo/