固定链接 基于 GitBook 搭建文档平台(一)

基于 GitBook 搭建文档平台(一)

基于 GitBook 搭建文档平台(一)

Gitbook 是一个基于 Node.js 的命令行工具,可以使用 GitHub/Git 和 MarkDown 来制作精美的电子书。

在我们平时的工作中,所有的项目都需要配备对应的使用说明文档。而 GitBook 以其良好的性能,及简单的搭建方式适用于文档或博客系统的搭建。

下面就让我们一起用 GitBook 来创建一本文档书吧。

Node 环境配置

GitBook 是基于 Node.js 实现的,下载并安装 Node.js:

GitBook 安装

GitBook 通过 NPM 安装:

检测安装是否成功:

构建书籍

初始化书籍

我们在自定义文档内容之前,需要通过 GitBook 命令在当前目录下创建一本书:

创建书籍后,使用下面命令预览您的书籍:

或者使用以下命令构建静态网站:

代码结构

一般 GitBook 项目文件的结构如下:

book.json

为了满足不同人的需求,GitBook 允许用户使用灵活的配置自定义书籍。在根目录下创建 book.json 文件,通过配置 book.json 文件来修改编译书籍时的一些个性化配置。

常规配置如下:

变量 作用
title 书籍标题,从 README.md 中提取,默认为 Introduction
author 书籍作者
language 文档语言,默认 en
description 文档描述
plugins 插件使用的加载列表
pluginsConfig 插件配置
variables 用户自定义变量
gitbook 版本信息

SUMMARY.md

GitBook 通过读取 SUMMARY.md 文件定义书籍菜单。根据其中的内容结构对应生成 HTML。

SUMMATY.md 在 [] 内填写标题,在()内填写文档路径,其中章节和子章节通过 4 个空格件或者 tab 键进行目录的分级标识。

目录定义有两种方式:

  1. 分级菜单

  2. 分区菜单

主题

GitBook 为我们提供了三种不通的书籍主题,分别是:

  • theme-default
  • theme-faq
  • theme-api

可以通过配置 plugins 来进行主题的选择:

插件

通过上面的主题选择,我们可以发现插件是扩展 GitBook 功能的最佳方式。

plugins.gitbook.com 中可以轻松搜索插件。当有需要安装的插件,我们将它添加到你的 book.json 中,在 plugins 和 pluginsConfig 字段添加插件及相关配置。

我们以 Anchors 插件为例进行配置,该插件的主要功能是为标题添加锚点:

最后

在搭建文档平台的过程中,我们会发现 GitBook 现有的主题和插件不能够满足我们的需求,GItBook 也提供了自定义样式和插件的方式。

您的留言将激励我们越做越好