Gitbook安装与设置_gitbook 配置多语言切换-CSDN博客

本文链接：https://blog.csdn.net/lili40342/article/details/123548107

在这里插入图片描述

Windows系统

安装 Gitbook 需要 nodejs 环境，请事先安装并配置 nodejs 环境，这里就不多做讲解了，您可以移步到作者的相关文章中查看：使用nvm管理node和npm 和解压版的nodejs安装与配置

配置与安装

安装并配置 nodejs 环境之后，通过 node -v 命令验证没有问题之后就可以进行 Gitbook 的安装了。前提必须要说一下，请使用系统管理员打开 CMD 控制窗口，步骤如下：

使用 npm 命令安装 gitbook-cli，它是在同一系统上安装和使用多个版本的 Gitbook 的实用程序，它将自动安装所需版本的 Gitbook 程序。命令如下：
```
#可能需要一些时间，耐心等待
npm install -g gitbook-cli
```
上一步执行完毕后，通过 gitbook -V 命令查看是否安装成功，注意 V 是大写。命令如下：
```
#这一步时间超级长，不要认为你机器有问题或者网络有问题
#有报错或者警告也别管，死等即可，出去溜一圈就行
gitbook -V
```
切记，一定要死等结束，真的非常慢这一步。
等上一步执行完了再执行一遍 gitbook -V 命令就会立刻列出相应的信息，到这里 Gitbook 是安装完毕了。

使用 Gitbook 创建并管理书

Gitbook 安装完毕就可以创建自己的本地书籍了，在指定地方创建个文件夹（名字自定义即可，英文），CMD 控制台 cd 进入刚才创建的文件夹目录，进行初始化。命令如下：

gitbook init

执行完了 gitbook init 命令，会在刚才的文件夹目录下生成两个文件：README.md 和 SUMMARY.md，这两个文件不能删除，也不能改名。其中 README.md 是说明文件，SUMMARY.md 是目录文件。

既然都是 md 类型的文件，就可以用 Markdown 编辑对它们进行编辑，选什么编辑器看个人喜好，作者用的是 Typora。

下面对 Gitbook 进行详解讲解。

目录结构

一般情况下目录结构如下：

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

目录文件的主要功能：

文件名	描述
book.json	配置数据 (可选)，但是作者认为必须得有，个人习惯
README.md	电子书的前言或简介 (必需)
SUMMARY.md	电子书目录 (作者认为它必须存在)
GLOSSARY.md	词汇/注释术语列表 (可选)，作者从没用过

菜单结构

一个本的菜单什么样的，取决于 SUMMARY.md 文件，这就是刚才作为为什么认为它必须存在的原因。

指定菜单项目的标题。
( ) 指定菜单文章文件的路径。
支持子目录的方式，章节和子章节用 tab 键来分级。
# 或者 — 进行不同 Part 的分类，分别由标题或者水平分割线方式表示不同的部分。
区域导航定位，在章节路径 md 文件结尾使用 # 号加上文章内容中章节的标题就能实现区域导航。

写了这么多，我觉得只要会 Markdown 语法，没有任何难度。如下：

# Summary

### 第I部分

* [第I部分](part1/README.md)
    * [标题1](part1/README.md#one)
    * [标题2](part1/README.md#two)

### 第II部分

* [第II部分](part2/README.md)
    * [标题1](part2/README.md#one)
    * [标题2](part2/README.md#two)

----

* [第III部分](part3/three.md)

以上内容仅供参考。

页面文件

Gitbook 书籍的页面文件采用的 Markdown 语法实现的，所以只要你懂 Markdown 语法就可以编辑对应的页面按文件。具体的相关的 Markdown 语法不熟悉的可以参考：菜鸟教程，MarkDown中文网或者其它的参考网站。

其它

其它还包括一些细节配置，作者认为没有什么必要可描述的。比如页面顶部可以使用 YAML 格式来定义描述信息，这不是必须的，有兴趣的可以自行搜索。再比如专业术语，忽略文件等等配置，作者也没用上，所以还是请您自行搜索。

配置和说明（book.json文件）

Gitbook 还有一些配置可进行设置，主要集中在 book.json 文件中，既然是 json 文件，请一定存储 json 语法格式要求（有注释信息好像也不行），否则在生成 Gitbook 书的时候会报错。

注意：在创建 book.json 文件时，请一定将 book.json 文件保存为 UTF-8 编码格式的，要不中文信息在生成书籍的时候会出现乱码。

具体的 book.json 文件中的配置概览，如下：

变量	说明
root	包含所有图书文件的根文件夹的路径，除了 book.json 文件
title	书籍的标题，默认值从README中提取
description	籍说明，默认值从自述文件中提取，其实就是生成html里面的那个meta描述
author	作者姓名，其实就是生成html里面的那个meta作者描述
isbn	书籍的国际码ISBN
language	语言规范中的语言规范定义，默认值是 en，汉字选用 zh-hans
gitbook	GitBook 的版本，使用 SemVer 规范并接受诸如 “>=3.0.0” 的条件
structure	指定自述，摘要，词汇表等的路径
variables	这个选项定义书籍中的变量，就是自定义变量
links	在左侧导航栏最上添加指定的自定义链接
styles	用来自定义书本的 css
plugins	指定书籍使用的插件列表
pluginsConfig	配置指定插件的一些配置信息
pdf	导出 PDF 文件的一些配置信息

基础配置

参考如下：

{
    "root":".",
    "author":"Lee",
    "title":"Lee Gitbook",
    "language":"zh-hans",
    "description":"This is gitbook",
    "isbn":"000-0-00-000000-0",
    "direction":"ltr",
    "gitbook":">=3.2.3"
}

structure 结构配置

变量	说明
structure.readme	自述文件名（默认为“README.md”）
structure.summary	摘要文件名（默认为“SUMMARY.md”）
structure.glossary	词汇表文件名（默认为“GLOSSARY.md”），作者没用过
structure.languages	语言文件名（默认为LANGS.md)，作者没用过

参考如下：

{
    "structure":{
        "readme":"README.md",
        "summary":"SUMMARY.md"
    }
}

variables 变量配置

定义一些书籍中的变量信息，定义在 book.json 中的变量可以在 book 作用域下被访问，如：{{ book.blog }} 双括号语法在书籍中获取其中的数值（说实话用的不多，作者也没用过，个人认为可有可无）。

参考如下：

{
    "variables":{
        "blog":"https://blog.csdn.net/lili40342"
    }
}

links 链接导航

通过 links 配置在左侧导航栏添加指定的链接导航，如：添加自己的博客链接，GIthub链接等等…

参考如下：

{
   "links": {
        "sidebar": {
            "CSDN": "https://blog.csdn.net/lili40342",
			"Gitee": "https://gitee.com/lili40342"
        }
    }
}

styles 自定义样式

通过 styles 配置这个选项用来自定义书本的 css 的。

参考如下：

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

pdf 参数配置

PDF输出可以使用book.json中的 pdf 来进行配置：

变量	说明
pdf.pageNumbers	将页码添加到每个页面的底部（默认为true）
pdf.fontSize	基本字体大小（默认为12）
pdf.fontFamily	基本字体系列（默认为Arial）
pdf.paperSize	纸张大小，选项为：“a0”，“a1”，“a2”，“a3”，“a4”，“a5”，“a6”，“b0”，“b1”，“b2”，“b3”, “b4”，“b5”，“b6”，“legal”，“letter”，（默认为"a4"）
pdf.margin.top	顶部边距（默认为56）
pdf.margin.bottom	底边距（默认为56）
pdf.margin.left	左边距（默认为62）
pdf.margin.right	右边距（默认为62）

参考如下：

{
   "pdf": {
		"pageNumbers": true,
		"fontFamily": "Arial",
		"fontSize": 12,
		"paperSize": "a4",
		"margin": {
			"right": 62,
			"left": 62,
			"top": 56,
			"bottom": 56
		}
	}
}

plugins 插件列表

通过 plugins 配置可以配置书籍需要的插件列表。

参考如下：

{
    "plugins": [
        "github",
        "splitter",
        ...
    ]
}

pluginsConfig 插件配置

通过插件配置可以配置插件列表plugins中对应插件的一些配置选项信息。

参考如下：

{
    "plugins": ["favicon"],
    "pluginsConfig": {
        "favicon": {
            "shortcut": "favicon.ico",
			"bookmark": "favicon.ico"
        }
    }
}

总体参考配置示例

最后贴出作者经常用的一个 book.json 完整的配置，可供参考。

{
	"root": "src",
	"author": "WorkerLee",
    "title": "这标题",
    "description": "这是描述",
    "language": "zh-hans",
	"direction": "ltr",
    "gitbook": ">=3.2.3",
	"structure": {
		"readme": "README.md",
        "summary": "SUMMARY.md"
    },
    "links": {
        "sidebar": {
            "CSDN": "https://blog.csdn.net/lili40342",
			"Gitee": "https://gitee.com/lili40342"
        }
    },
	"styles": {
	    "website": "styles/website.css",
	    "ebook": "styles/ebook.css",
	    "pdf": "styles/pdf.css",
	    "mobi": "styles/mobi.css",
	    "epub": "styles/epub.css"
	},
	"plugins": [
        "-lunr",
        "-search",
		"search-pro",
        "advanced-emoji",
        "tbfed-pagefooter",
        "splitter",
        "anchor-navigation-ex",
		"expandable-chapters-small",
        "code",
		"copy-code-button",
        "alerts",
		"hide-element",
		"favicon",
		"lightbox",
		"-sharing"
    ],
	"pluginsConfig": {
		"hide-element": {
            "elements": [".gitbook-link"]
        },
		"favicon": {
			"shortcut": "favicon.ico",
			"bookmark": "favicon.ico"
		},
		"tbfed-pagefooter": {
			"copyright": "Copyright &copy WorkerLee",
			"modify_label": "更新时间：",
			"modify_format": "YYYY-MM-DD HH:mm:ss"
		},
		"anchor-navigation-ex": {
			"showLevel": false,
			"associatedWithSummary": false,
			"printLog": false,
			"multipleH1": false,
			"mode": "float",
			"showGoTop": true,
			"float": {
				"floatIcon": "fa fa-navicon",
				"showLevelIcon": false,
				"level1Icon": "fa fa-angle-double-right",
				"level2Icon": "fa fa-angle-double-right",
				"level3Icon": "fa fa-angle-double-right"
			},
			"pageTop": {
				"showLevelIcon": false,
				"level1Icon": "fa fa-hand-o-right",
				"level2Icon": "fa fa-hand-o-right",
				"level3Icon": "fa fa-hand-o-right"
			}
		}
	},
	"pdf": {
		"pageNumbers": true,
		"fontFamily": "Arial",
		"fontSize": 12,
		"paperSize": "a4",
		"margin": {
			"right": 62,
			"left": 62,
			"top": 56,
			"bottom": 56
		}
	}
}

至于一些其它的插件，一些主题，具体有什么用，怎么用，还是请各位自行搜索，这里就不多讲解了。

生成书籍

README.md 和 SUMMARY.md 文件内容也维护好了，相应的子页面的内容也编辑好了，book.json 文件也配置版好了，下面就可以生成我们想要的 Gitbook 书了。可以再次使用“gitbook init”命令生成个目录中的各小节md文件，然后你喜欢手动创建也没有任何问题。

安装插件

book.json 文件中会配置很多插件，这些插件默认情况下，有一些是不在本机的，需要先进行插件的安装，命令如下：

#直接进行所有的插件安装，根据配置插件多少决定时间长短，命令运行后有信息提示安装到哪个插件了
#也可以单个插件逐一安装，命令请自行搜索
#这里只给出安装所有插件
gitbook install

编译生成

Gitbook 编译会在当前书籍目录下生成一个“_book”文件夹，里面是一些编译好的静态页面，其实所谓编译生成，就是默认的生成静态 HTML 页面（可直接浏览器查看）。编译命令如下：

gitbook build

在线预览

我们可以通过 nodejs 的平台支撑将编译好的静态页面通过服务器形式进行在线预览访问，Gitbook 默认开启一个 4000 的端口服务，在浏览器中直接可以通过 http://localhost:4000 进行访问。启动服务命令如下：

#看好命令，是serve，并不是server
#并确定好您本机4000端口可用
gitbook serve

到此基本就OK了。

总结（可能遇到问题）

Gitbook 命令

#初始化，其实可以理解为设置一个样板书
gitbook init
#如果初始化到一个新创建的目录中
gitbook init ./directory
#构建生成静态资源
gitbook build
#可以在构建生成资源的时候查看更详细的信息
gitbook build ./ --log=debug --debug
#启动服务
gitbook serve

#列出gitbook所有的命令
gitbook help
#列出gitbook-cli所有的命令
gitbook --help
#生成时指定gitbook的版本, 本地没有会先下载
gitbook build --gitbook=2.0.1
#列出本地所有的gitbook版本
gitbook ls
#安装对应的gitbook版本
gitbook fetch 标签/版本号
#更新到gitbook的最新版本
gitbook update
#卸载对应的gitbook版本
gitbook uninstall 2.0.1

遇到的问题

安装过程中，可能会遇到各种各样的问题，主要错误大家也一定是一个，作者也不挨个表述了，自行搜索即可。但是作者认为，只要保证各个组件的版本兼容，不太会出问题，比如我一直阐述的 nodejs 版本要和 npm 版本进行兼容对应，或者是不要下载太新的版本等等。

推送到 Gitee 或者 GitHub

将 Gitbook 做成自己的知识分享也是不错的选择，具体怎么推送这里也不阐述了，很简单，一搜一大把。

导出 PDF、ePub、Mobi格式文件

目前常见的电子书格式主要主要有三种（ePub, Mobi, PDF），在 Gitbook 中导出这三种格式都依赖于系统本身提供的 ebook-convert 工具支持。所以要想导出 PDF、ePub、Mobi 格式文件，需要先安装 ebook-concert 依赖。相关的信息还需要访问：https://calibre-ebook.com/download，查看相关对应的系统进行相应的安装。

作者认为现在市面上支持 ePub、Mobi 格式的工具较少，所以大部分还是生成 PDF 更合适，但是既然我们用了 Markdown 编辑器，大部分的 Markdown 编辑器都具有到处 PDF 格式的功能，看您怎么选择了。