gitbook简单教程

Posted 2020-10-20 从零开始的异世界

简介

GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书。GitBook支持输出以下几种文档格式

静态站点：GitBook默认输出该种格式

PDF：需要安装gitbook-pdf依赖

eBook：需要安装ebook-convert

准备安装

在使用GitBook 之前, 我们需要先安装一些必须的工具:

• Node.js
• GitBook
• GitBookEditor
• Git版本控制器。

Node.js

Node.js是一个基于 Chrome V8 引擎javascript 运行环境。

• Node.js 使用了一个事件驱动、非阻塞式 I/O 的模型，使其轻量又高效。
• Node.js 的包管理器 npm, 是全球最大的开源库生态系统。

Node.js 下载（windows）

Node.js中文网

检查是否安装成功

node -v

gitbook

//全局安装
npm install gitbook -g

gitbook-cli

//全局安装，你将有权访问系统上的任何地方的gitbook命令
npm install -g gitbook-cli

Git

Git是一款免费、开源的分布式版本控制系统，用于敏捷高效地处理任何或小或大的项目。基本安装请点击安装教程。如果不需要从GitHub更新书到本地再编译，则可以不安装Git。

GitBookEditor

GitBook官方客户端编辑器，支持Win、Linux、Mac系统。请点击下载GitBookEditor。使用该编辑器可以快速的创建、编辑GitBook。

基本使用

GitBook 大致分为两种使用方式，即离线和在线。最简单的使用方式是使用GitBook Editor编辑GitBook ，然后使用相关命令编译成功html。当然还有以下几种方式

• 使用命令创建基本GitBook
• 使用网页在线编辑器创建、编辑GitBook。
• 使用itBookEditor客户端创建、编辑GitBook。

高级扩展

掌握了“基本使用”，但有时候想要gitBook更美观，或者更符合我们自己的需求，则通过book.json配置进行自定义、以及安装一些常用的插件等。

本地项目构建

新建文件夹gitbook, 在文件夹下创建下面3个文件

• README.md 关于文档，在 SUMMARY.md 进行配置
• SUMMARY.md 文档目录
• book.json 文档框架，最核心的文件

1.SUMMARY.md

文档的目录结构，所有需要展示的文档都需要在它里面进行罗列。

详细 GitBook 官方英文文档

# Summary
* [前言](README.md)

2.book.json

示例:

{
    "root": "./",
    "title": "示例文档",
    "head_title": "_示例文档_字条网",
    "head_description": "示例文档",
    "head_keywords": "示例文档",

    "gitbook": ">= 3.0.0",

    "language": "zh-hans",

    "plugins": [
        "-sharing",
        "-fontsettings",
        "-lunr",
        "-search",
        "search-pro",
        "theme-official",
        "sitemap-general"
    ],

    "pluginsConfig": {
        "sitemap-general": {
            "prefix": "http://zitiao.org/simple/"
        }
    }
}

安装依赖

在文件夹gitbook下运行:

//安装项目依赖
npm install

//安装gitbook依赖
gitbook install

//会安装所需的所有插件，当自动打印如下文字，代表安装成功：
info: >> plugin "sitemap-general" installed with success

编译文件

gitbook build

运行

gitbook serve

//当自动打印出如下文字，就代码运行成功：

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

在浏览器里访问 http://localhost:4000 就能看到文档了!

修改端口号

gitbook serve --port 4002

现在访问 http://localhost:4002 就可以看到端口号变成4002了！