Guide

1. 安装

# 卸载之前的Node.js版本
scoop uninstall nodejs -p
# 安装Node.js
scoop install main/nodejs@22.9.0
# 设置npm代理
npm config set proxy http://localhost:10809
npm config set https-proxy http://localhost:10809
# 法一: 使用默认镜像源
npm config set registry https://registry.npmjs.org
# 法二: 默认镜像源不能用则使用淘宝镜像源
# npm config delete registry
npm config set registry https://registry.npmmirror.com
# 安装gitbook-cli
npm install -g gitbook-cli
# 找到出错文件, 注释第62-64行
# E:\UserApps\persist\nodejs\bin\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js
  # // fs.stat = statFix(fs.stat)
  # // fs.fstat = statFix(fs.fstat)
  # // fs.lstat = statFix(fs.lstat)
# 安装GitBook
scoop install gendloopBucket/gitbook
# 查看当前版本
gitbook -V
# 安装calibre(用于生成电子书, 可选)
scoop install extras/calibre

2. gitbook 常用命令

Command       Description
gitbook help                  # 列出gitbook所有命令
gitbook --help                # 列出gitbook-cli所有命令
gitbook init                  # 生成初始化目录文件
gitbook build                 # 生成静态网页
gitbook serve                 # 生成静态网页并运行服务器
gitbook build --gitbook=2.6.5 # 生成时指定gitbook 版本
gitbook ls                    # 列出本地gitbook版本
gitbook ls-remote             # 列出远程gitbook版本
gitbook fetch 2.6.5           # 安装远程gitbook版本
gitbook update                # 更新到gitbook最新版本
gitbook uninstall 2.6.5       # 卸载指定gitbook版本

3. 创建新项目

3.1. 项目结构

.
├── book.json
├── README.md
├── INTRO.md
├── SUMMARY.md
├── GLOSSARY.md
├── styles/
├── res/
└── chapters/
    ├── chapter1/
    |   ├── README.md
    |   └── something.md
    └── chapter2/
        ├── README.md
        └── something.md

3.2. 基本流程

# 创建项目目录
mkdir TestGitBook
cd TestGitBook
gitbook init  # => README.md, SUMMARY.md
# 生成静态网页并运行服务器 http://localhost:4000
gitbook serve # 默认使用 35729 端口给 4000 端口提供服务
# 或自定义端口 gitbook serve --lrport 35728 --port 4001
# 仅生成网页
gitbook build
# 仅生成pdf
gitbook pdf
# 仅生成epub
gitbook epub
# 仅生成mobi
gitbook mobi

4. 封面

在根目录添加cover.jpg文件, cover_small.jpg可作为小版本封面存在

5. 多语言

在根目录下添加LANGS.md, 每种语言需作为一个子目录

可参考GitbookIO/git: ProGit Book Fork generated using GitBook (github.com)

6. 术语表

在根目录下添加GLOSSARY.md, 格式为

## Word1
不支持中文
## Word1 Word2
不支持中文

7. 转义*

// todo

8. 引用*

// todo

9. 继承*

// todo

10. 自定义配置

在根目录下创建book.json文件, 包含的字段如下

粘贴内容到JSON Lint可验证JSON语法

10.1. gitbook

探测用来生成书本的gitbook的版本

{ "gitbook": "3.2.3" }
{ "gitbook": ">=3.2.3" }

10.2. title

{ "title" : "How To Use GitBook" }

10.3. author

{ "author": "gendloop" }

10.4. description

定义书本的描述, 默认从 README (第一段) 中提取

{ "description": "This is such a great book!" }

10.5. language

可选语言

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", # 简体中文 }

10.6. root

{ "root": "." }

10.7. links

10.8. isbn

定义书本的 ISBN

{ "isbn": "978-3-16-148410-0" }

10.9. direction

设置语言的文字方向

{ "direction": "rtl" }

10.10. styles

自定义书本的 css

{
  "styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
  }
}

10.11. plugins

{ "plugins": ["mathjax"] }

10.12. pluginsConfig

{
  "plugins": ["myplugin"],
  "pluginsConfig": {
    "myPlugin": {
        "message": "Hello World"
    }
  }
}

10.13. structure

用来覆盖GitBook使用的路径的。

例如你想要使用INTRO.md代替README.md：

{
  "structure": {
    "readme": "INTRO.md"
  }
}

10.14. variables

定义在模板中使用的变量值

{
  "variables": {
    "myVariable": "Hello World"
  }
}

11. 插件

11.1. 查找插件

输入npm search gitbook-plugin可搜索部分插件, 更多在此搜索https://www.npmjs.com/

11.2. 安装插件

1. 添加到 book.json

    {
      "plugins": ["myPlugin@2.3.2", "anotherPlugin"]
    }
   

2. 执行npm install安装所有缺失的插件

   执行npm install gitbook-plugin-myPlugnin@2.3.2可安装特定的插件

11.3. 部分插件说明

https://gendloop.github.io/GitBookPlugins/

12. 拓展网站和电子书样式

通过在styles目录中建立文件来扩展

Type          File
website       'styles/website.css'
pdf           'styles/pdf.css    '
epub          'styles/epub.css   '
mobi          'styles/mobi       '
pdf,epub,mobi 'styles/ebook.css  '

这些路径可以在book.json设置中改变，例如使用根文件夹中的文件：

{
  "styles": {
    "website": "website.css",
    "ebook": "ebook.css",
    "pdf": "pdf.css",
    "mobi": "mobi.css",
    "epub": "epub.css"
  }
}

13. 数学 & Tex

有两个官方的插件用来显示数学公式：mathjax和katex

14. 构建*

// todo

15. 可参考的GitBook项目

• honkit/honkit: HonKit is building beautiful books using Markdown - Fork of GitBook

16. References

1. https://chrisniael.gitbooks.io/gitbook-documentation/content/index.html
2. http://gitbook.zhangjikai.com/
3. https://www.zhaowenyu.com/gitbook-doc/
4. 简介-GitBook 简明教程-码谱
5. http://gitbook.zhangjikai.com/plugins.html#gitbook
6. https://www.cnblogs.com/jiangming-blogs/p/14643147.html (插件使用)
7. gitbook serve后报错：Error ENOENT_ no such file or directory……__book_gitbook_gitbook - 柳仙慧子 - 博客园.html
8. Gitbook的安装和部署 - 快乐的提千万 - 博客园.html
9. node.js - Gitbook-cli install error TypeError_ cb.apply is not a function inside graceful-fs - Stack Overflow.html
10. 2021年gitbook的安装报错，一次解决方案！ - 握着玫瑰的屠夫 - 博客园.html