GitBook 准备工作
安装 Node.js
GitBook 是一个基于 Node.js 的命令行工具,下载安装 Node.js,安装完成之后,你可以使用下面的命令来检验是否安装成功。
1 | $ node -v |
安装 GitBook
输入下面的命令来安装 GitBook。
1 | $ npm install gitbook-cli -g |
安装完成之后,你可以使用下面的命令来检验是否安装成功。
1 | $ gitbook -V |
更多详情请参照 GitBook 安装文档 来安装 GitBook。
安装 GitBook 编辑器
去 GitBook 官网 下载 GitBook 编辑器;如果是 Mac 用户且安装过 brew cask
的话可以使用 brew cask install gitbook-editor
命令行来安装 GitBook 编辑器。
先睹为快
GitBook 准备工作做好之后,我们进入一个你要写书的目录,输入如下命令。
1 | $ gitbook init |
可以看到他会创建 README.md 和 SUMMARY.md 这两个文件,README.md 应该不陌生,就是说明文档,而 SUMMARY.md 其实就是书的章节目录,其默认内容如下所示:
1 | # Summary |
接下来,我们输入 $ gitbook serve
命令,然后在浏览器地址栏中输入 http://localhost:4000
便可预览书籍。
效果如下所示:
运行该命令后会在书籍的文件夹中生成一个 _book
文件夹, 里面的内容即为生成的 html 文件,我们可以使用下面命令来生成网页而不开启服务器。
1 | gitbook build |
下面我们来详细介绍下 GitBook 目录结构及相关文件。
目录结构
GitBook 基本的目录结构如下所示:
1 | . |
下面我们主要来讲讲 book.json 和 SUMMARY.md 文件。
book.json
该文件主要用来存放配置信息,我先放出我的配置文件。
1 | { |
相信很多节点自己也能猜到是什么意思,我还是简单介绍下吧。
title
本书标题
author
本书作者
description
本书描述
language
本书语言,中文设置 “zh-hans” 即可
gitbook
指定使用的 GitBook 版本
styles
自定义页面样式
structure
指定 Readme、Summary、Glossary 和 Languages 对应的文件名
links
在左侧导航栏添加链接信息
plugins
配置使用的插件
pluginsConfig
配置插件的属性
SUMMARY.md
这个文件主要决定 GitBook 的章节目录,它通过 Markdown 中的列表语法来表示文件的父子关系,下面是一个简单的示例:
1 | # Summary |
这个配置对应的目录结构如下所示:
我们通过使用 标题
或者 水平分割线
将 GitBook 分为几个不同的部分,如下所示:
1 | # Summary |
这个配置对应的目录结构如下所示:
插件
GitBook 有 插件官网,默认带有 5 个插件,highlight、search、sharing、font-settings、livereload,如果要去除自带的插件, 可以在插件名称前面加 -
,比如:
1 | "plugins": [ |
如果要配置使用的插件可以在 book.json 文件中加入即可,比如我们添加 plugin-github,我们在 book.json 中加入配置如下即可:
1 | { |
然后在终端输入 gitbook install ./
即可。