一文教你使用 Gitbook 部署电子书到云端

Yorkyu

发布于 2022-03-22 15:39:13

2.1K00

代码可运行

文章被收录于专栏：约克编程技术约克编程技术

运行总次数：0

代码可运行

作者：约克
原文地址：https://yorkyu.cn/deploy-gitbook-on-cloud-54ac5bddf02d.html
文章版权归作者所有，转载请注明出处！

前言

文章教你如何使用 Gitbook 创建电子书，介绍 Gitbook 常用插件。并把其部署到腾讯云 COS，进行 CDN 加速，SEO 优化等。

一. Gitbook 简介

1.1. 介绍

GitBook.com GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书，并托管图书的在线平台。它提供托管，协作功能和易于使用的编辑器。

1.2. CLI 工具

使用 Gitbook 提供的命令行工具管理电子书可显著提高效率，也符合编程开发习惯。gitbook-cli 安装命令。

# 安装 gitbook-cli 工具
$ npm install gitbook-cli -g

# 查看版本
$ gitbook -V

1.3. CLI 常用命令

# 使用模版，初始化电子书
$ gitbook init

# 本地启动，预览电子书
$ gitbook serve

# 构建电子书
$ gitbook build

# 查看电子书命令
$ gitbook help

# 列出本地电子书版本
$ gitbook ls

# 列出远程可用的gitbook版本
$ gitbook ls-remote

# 更新到gitbook的最新版本
$ gitbook update

1.4. 电子书目录结构

Gitbook 电子书目录结构，本文参考电子书 nxtech-regexp 点击查看

.
├── _book # 构建电子书静态文件
├── book.json # gitbook 配置文件
├── docs # 电子书正文
│   ├── README.md # 电子书首页
│   ├── SUMMARY.md # 电子书左侧导航
│   ├── chapter-1 # 电子书章节
│   └── styles # 自定义电子书样式
└── env.sh # 环境变量替换脚本

二. book.json 配置

GitBook 允许使用灵活的配置自定义电子书风格。这些选项在 book.json 文件中指定。gitbook 在编译书籍的时候会读取书籍源码顶层目录中的 book.js 或 book.json。

book.json 参考配置如下，点击查看详情。

{
  "title": "一起学RegExp",  // 书名
  "author": "yorkyu",   // 作者
  "root": "./docs", // 包含所有图书文件的根文件夹的路径
  "description": "xxx", // 书籍的描述
  "plugins": [],    // 插件列表
  "styles": {   // 自定义样式
    "website": "styles/website.css"
  },
  "pluginsConfig": {},  // 插件配置
  "links" : {
    "sidebar" : {   // 左侧导航链接
      "一起学习 RegExp" : "/regexp/"
    }
  }
}

三. 常用插件

3.1. 插件命名规范

gitbook 有很多实用性插件，插件命名形如 gitbook-plugin-*，用户可以在 GitHub 或者 NPM 上搜索 gitbook-plugin 来查找。

3.2. 使用插件

在 book.json 中引用插件，并配置插件参数。通常插件列表中的只需写插件名 gitbook-plugin-* 星号 (*) 部分即可。

{
  "plugins": [    // 插件列表
    "sitemap",
    "theme-api",
    "-sharing",
    "back-to-top-button",
    "code",
    "copy-code-button",
    "search-pro",
    "splitter",
    "-sharing-plus",
    "page-footer-ex",
    "favicon",
    "popup",
    "minifier",
    "url-embed",
    "github"
  ],
  "pluginsConfig": {  // 插件配置
    "sitemap": { // sitemap 插件
      "hostname": "https://book.yorkyu.cn"
    },
  },
}

3.3. 安装依赖插件

当在 book.json 配置好依赖插件后，在 book.json 同级目录执行下述命令安装依赖插件。

$ gitbook install

3.4. 插件列表

gitbook-cli 可使用用插件 plugin 扩展能力，常用的插件 plugin 如下表格所示：

插件名称	插件功能	插件地址
gitbook-plugin-sitemap	生成搜索引擎 sitemap.xml	点击查看
gitbook-plugin-theme-api	Gitbook Api 主题	点击查看
gitbook-plugin-back-to-top-button	返回顶部	点击查看
gitbook-plugin-code	代码块添加行号，复制按钮	点击查看
gitbook-plugin-search-pro	支持中文搜索	点击查看
gitbook-plugin-splitter	侧边栏宽度可调节	点击查看
gitbook-plugin-page-footer-ex	文章底部扩展描述信息	点击查看
gitbook-plugin-favicon	定义favicon	点击查看
gitbook-plugin-popup	新窗口打开图片	点击查看
gitbook-plugin-minifier	构建压缩静态文件	点击查看
gitbook-plugin-github	添加 Github 图标	点击查看
plugin-sharing	添加分享图标	点击查看

四. 与 Github 集成

Gitbook 与 GitHub 的集成非常易于使用，如果您在 GitBook 上更改内容，则所做的编辑将推送到 GitHub 存储库中。反之亦然。点击查看详情

4.1. 设置集成步骤

在您的空间中，点击 integrations tab > GitHub
授权 GitBook 访问您的 GitHub 帐户
选择您要连接的存储库

4.2. Github 查看

当 4.1. 执行成功后，则可在 Github 仓库中查看到 Gitbook 内容。点击查看参考示列

五. Gitbook部署到云端

由于 Gitbook 托管的电子书在国内访问较慢，体验较差，因此作者探索了将 Gitbook 部署到腾讯云的方案，并将其记录下来，供大家参考。

5.1. 域名复用

由于作者后续会陆续写多本 Gitbook，想将不同的电子书挂载同一域名 book.yorkyu.cn 下，通过 /regexp/ 域名更路径标志。形如：

# 一起学习 RegExp
https://book.yorkyu.cn/regexp/

# 一起学习微前端
https://book.yorkyu.cn/micro-frontend

5.2. 路径替换

由于 gitbook-cli 提供的构建插件不支持自定义 basepath，在不同电子书复用同一域名 book.yorkyu.cn 时首页会出现资源加载失败的情况。针对该种情况，作者使用 shell 脚本 env.sh 进行处理。点击查看

#!/bin/bash
# 替换 index.html 入口文件中的静态文件路径
sed -i -e 's@".gitbook\/@'\".\/.gitbook\/'@g' ./_book/index.html
sed -i -e 's@"gitbook\/@'\".\/gitbook\/'@g' ./_book/index.html
# 替换首页左侧导航路径
sed -i -e 's@"introduction\/@'\".\/introduction\/'@g' ./_book/index.html
sed -i -e 's@"grammar\/@'\".\/grammar\/'@g' ./_book/index.html
sed -i -e 's@"complex-regexp-analysis\/@'\".\/complex-regexp-analysis\/'@g' ./_book/index.html
sed -i -e 's@"common-regex\/@'\".\/common-regex\/'@g' ./_book/index.html
sed -i -e 's@"application-scenario\/@'\".\/application-scenario\/'@g' ./_book/index.html
sed -i -e 's@"advanced\/@'\".\/advanced\/'@g' ./_book/index.html
# 替换 sitemap.xml 中的路径
sed -i -e 's@book.yorkyu.cn\/@'book.yorkyu.cn\/regexp\/'@g' ./_book/sitemap.xml

六. 电子书存到云端

该步骤可参考六，博客存到云端。由于不同电子书需挂载在同一域名 book.yorkyu.cn 下，因此在 COS 中需把不同的电子书放在一个独立的目录中，参考下图：

七. 电子书发布到云端

该步骤可参考七，博客发布到云端。

八. 自定义域名

该步骤可参考八，云端自定义博客域名。

九. SEO 优化

9.1. sitemap.xml

前述使用插件 gitbook-plugin-sitemap 生成了电子书的 sitemap.xml 。在使用 coding-ci 发布电子书时，需把每本电子书的 sitemap.xml 移动到 COS 通的根目录下，命名参考 regexp_sitemap.xml。其中上传 COS 的命令修改为如下：

coscmd upload -r ${COS_UPLOAD_FROM_PATH} /regexp && coscmd upload ${COS_UPLOAD_FROM_PATH}sitemap.xml /regexp_sitemap.xml

9.2. 设置站点地图

列入在 Google Search Console Tools 设置站点地图。

9.3. 查看收录

参考

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2020年11月8日，如有侵权请联系 cloudcommunity@tencent.com 删除

javascript

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度