如何搭建 GitBook

程序员都喜欢使用 Markdown 来撰写文档，无论是开发用的技术文档，还是自己的学习总结文档，都离不开 Markdown ，今天给大家介绍一款高效管理、发布 Markdown 文档的工具 - GitBook 。

关于 GitBook

首先来看一下 官方 的定义：

Modern documentation format and toolchain using Git and Markdown

GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc)

GitBook is a modern documentation platform where teams can document everything from products, to APIs and internal knowledge-bases.

GitBook 基于 Git 和 Markdown 来构建书籍，它可以将 Markdown 文件，按指定的目录结构生成网页（HTML）或者电子书（pdf、epub、mobi），其核心为 Node.js 包。

漂亮的渲染效果

多样化的模板

我们可以在 GitBook 官方平台 上创建书籍，也可以在本地搭建私有的 GitBook 平台，本文将介绍后者。

安装与初始化

1. 安装 Node.js 环境

要求 Node.js v4.0.0 及以上，可到 Node.js 下载并安装最新版本。

2. 通过 NPM 安装 GitBook

使用 Node.js 的包管理工具 NPM 来安装 GitBook 的命令行工具 gitbook-cli，通过它可以在电脑上安装和管理 GitBook 的多个版本的，并且能进行一些列的操作。

npm install gitbook-cli

1

3. 初始化 GitBook

GitBook 依赖于一些 特定名称 的文件，我们使用 gitbook init 命令来完成这些文件的初始化。

D:\MyBook>gitbook init

warn: no summary file in this book

info: create Learning tracker

info: create SUMMARY.md

info: initialization is finished

执行此命令，将自动在目录下创建 Learning tracker 和 SUMMARY.md 两个文件，这两个文件是 GitBook 必需的。

SUMMARY.md : 用于定义书籍的目录信息

Learning tracker : 书籍的简介

构建书籍

1. 构建目录

如上所述，SUMMARY.md 文件中定义了书籍的目录信息，可在该文件中通过 Markdown 的 列表语法 来构建书籍章节的层级关系。

假如我们的文件目录如下：

PS D:\MyBook> tree D:\MyBook /f

D:\MYBOOK

│ Learning tracker

│ SUMMARY.md

│

├─第一章 GitBook

│ GitBook插件.md

│ 关于GitBook.md

│ 安装与初始化.md

│

└─第二章 GitBook相关

Git的使用.md

Markdown语法介绍.md

编写如下的 SUMMARY.md：

# Summary

* [Introduction](Learning tracker)

* 第一章 GitBook

* [关于GitBook](第一章 GitBook/关于GitBook.md)

* [安装与初始化](第一章 GitBook/安装与初始化.md)

* 第二章 GitBook相关

* [Git的使用](第二章 GitBook相关/Git的使用.md)

* [Markdown语法介绍](第二章 Markdown语法介绍.md)

呈现的书籍目录：

我们还可以通过来增加 标题 和 下划线 来增加一些 分割效果。

# Summary

* [Introduction](Learning tracker)

## 基础篇

* 第一章 GitBook

* [关于GitBook](第一章 GitBook/关于GitBook.md)

* [安装与初始化](第一章 GitBook/安装与初始化.md)

## 进阶篇

* 第二章 GitBook相关

* [Git的使用](第二章 GitBook相关/Git的使用.md)

* [Markdown语法介绍](第二章 GitBook相关/Markdown语法介绍.md)

---

* 第三章 GitBook插件开发

* 插件原理

2. 启动服务

通过 gitbook build 命令可以将内容 （Markdown）编译成网页（HTML），生成的网页将存放在目录下的 _book 文件夹中。

GitBook 将根据 SUMMARY.md 中的内容来决定被编译的内容，并将它们链接起来。

通过 gitbook serve 启动一个本地服务，以预览书籍效果。

通常只需单独调用 gitbook serve命令，该命令会事先调用 gitbook build 命令

接下来可以在浏览器中访问：http://localhost:4000

配置与插件

可通过目录下的 book.json 文件来进行书籍配置，其中还可以配置一些插件。

1. 配置文件

插件前加 "-" 表示 Disable 该插件

用 "@" 来指定插件的版本，例如 "[email protected]"

通过 gitbook install 命令来安装 book.json 中登的插件

2. 插件介绍

下面介绍几款比较好用的插件，更多插件请访问 官方插件库。

expandable-chapters-small：目录折叠与展开

splitter：目录和内容的分割条，支持拖拽调整

edit-link：编辑按钮，可以设置一个链接，通常为GitHub对应项目

github：GitHub图标，可设置 GitHub项目链接

anchor-navigation-ex：页面内容导航

code：代码行号及 “复制” 按钮

tbfed-pagefooter：脚注

参考资料

插件库：https://plugins.gitbook.com

插件开发模板：GitbookIO/plugin

在线服务：Documentation made easy

书籍库：https://legacy.gitbook.com/explore

配置项详解：book.json | GitBook 简明教程

https://toolchain.gitbook.com

What is GitBook

学习gitbook - 极客教程

前言 · GitBook 使用教程

原文链接：如何搭建 GitBook_Iron 的博客-CSDN博客_搭建gitbook