如何搭建 GitBook

最新推荐文章于 2024-09-20 14:05:11 发布

Ironyho

最新推荐文章于 2024-09-20 14:05:11 发布

阅读量9.1k

点赞数 4

分类专栏： Other 文章标签： GitBook Markdown

本文链接：https://blog.csdn.net/Iron_Ye/article/details/83254911

版权

Other 专栏收录该内容

3 篇文章 0 订阅

订阅专栏

如何搭建 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 及以上，可到 nodejs.org 下载并安装最新版本。

2. 通过 `NPM` 安装 GitBook

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

npm install gitbook-cli

3. 初始化 GitBook

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

D:\MyBook>gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

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

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

构建书籍

1. 构建目录

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

PS D:\MyBook> tree D:\MyBook /f
D:\MYBOOK
│  README.md
│  SUMMARY.md
│
├─第一章 GitBook
│      GitBook插件.md
│      关于GitBook.md
│      安装与初始化.md
│
└─第二章 GitBook相关
        Git的使用.md
        Markdown语法介绍.md

编写如下的 SUMMARY.md：

# Summary

* [Introduction](README.md)
* 第一章 GitBook
    * [关于GitBook](第一章 GitBook/关于GitBook.md)
    * [安装与初始化](第一章 GitBook/安装与初始化.md)
* 第二章 GitBook相关
    * [Git的使用](第二章 GitBook相关/Git的使用.md)
    * [Markdown语法介绍](第二章 Markdown语法介绍.md)

呈现的书籍目录：

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

# Summary

* [Introduction](README.md)

## 基础篇
* 第一章 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 命令

PS D:\MyBook> gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: * plugins are installed
*** ***
info: >> generation finished with success in 2.2s !

Starting server ...
Serving book on http://localhost:4000

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

配置与插件

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

1. 配置文件

{
    "root": "./",
    "title": "我的博客",
    "author": "Iron",
    "authorHomepage": "https://blog.csdn.net/Iron_Ye",
    "description": "Iron 的 CSDN 博客",
    "language": "zh-hans",
    "copyright": "All Rights Reserved",
    "plugins": [
        "theme-code@0.0.20",
        "-sharing",
        "-lunr", 
        "-search",
        "search-pro",
        "splitter",
        "tbfed-pagefooter",
        "expandable-chapters-small",
        "github",
        "-sharing-plus",
        "code",
        "-copy-code-button",
        "anchor-navigation-ex",
        "edit-link"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"Copyright &copy Iron 2018",
            "modify_label": "修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "expandable-chapters":{},
        "theme-default": {
            "showLevel": false
        },
        "github": {
            "url": "https://github.com/Iron-YeHong"
        },
        "anchor-navigation-ex":{
            "showLevel": false
        },
        "edit-link": {
            "base": "https://github.com/Iron-YeHong",
            "label": ""
        }
    }
}