使用 github 发布 gitbook 电子书

william 收录于 Programming

2019-10-29 约 1200 字预计阅读 3 分钟

警告

本文最后更新于 2019-10-29，文中内容可能已过时。

gitbook 是一个用于生成现代电子书的工具，进过处理后可以得到mobi、pdf、静态网页等多种类型的书籍形式。对于生成后得到的静态网页，我们可以将其托管在 github 上面，使用 gh-pages 发布到网上，从而实现制作文档、发布知识分享。

本篇博客总结了如何配置 gitbook、如何制作静态网页、如何使用 github 托管等方面的技巧。

安装软件

安装 gitbook

需要使用 npm 执行命令

1

npm install gitbook -g

安装完成后，可以使用命令查找具体的可执行文件所在目录

1

whereis gitbook

查看具体的版本号

1

/opt/node-v12.10.0-linux-x64/bin/gitbook -V

基本命令

初始化，会自动生成 README.md 以及 SUMMARY.md
1

gitbook init
生成静态网页，会得到 _book 的目录
1

gitbook build
本地预览
1

gitbook serve

安装插件

由于使用的插件需要嵌入到静态网站，通常的做法是直接配置一个 book.json 的文件，里面会填入托管网站相关的信息，以及需要使用的配置参数。比如

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82


{
    "author": "方莲",
    "description": "To be betteR.",
    "title": "betteR",
    "variables": {},
    "extension": null,
    "generator": "site",
    "isbn": "",
    "links": {
        "sharing": {
            "all": null,
            "facebook": null,
            "google": null,
            "twitter": null,
            "weibo": null
        },
        "sidebar": {
            "William's Blog": "https://williamlfang.github.io/"
        }
    },
    "output": null,
    "pdf": {
        "fontSize": 12,
        "footerTemplate": null,
        "headerTemplate": null,
        "margin": {
            "bottom": 36,
            "left": 62,
            "right": 62,
            "top": 36
        },
        "pageNumbers": false,
        "paperSize": "a4"
    },
    "plugins": ["chapter-fold",
                "expandable-chapters-small",
                "expandable-chapters",
                "advanced-emoji",
                "github",
                "splitter",
                "-sharing", "sharing-plus",
                "simple-page-toc",
                "copy-code-button",
                "page-toc-button",
                "klipse",
                "pageview-count",
                "popup",
                "tbfed-pagefooter",
                "todo",
                "prism", "-highlight"
                ],
    "pluginsConfig": {
        "github": {"url": "https://github.com/williamlfang"},
        "sharing": {
                   "douban": true,
                   "google": true,
                   "twitter": true,
                   "weibo": true,
                   "all": [
                       "google", "twitter", "weibo"
                   ]
               },
        "simple-page-toc": {
                "maxDepth": 3,
                "skipFirstH1": true
                },
        "page-toc-button": {
            "maxTocDepth": 3,
            "minTocSize": 3
           },
        "tbfed-pagefooter": {
                    "copyright":"",
                    "modify_label": "该文件最后修改时间：",
                    "modify_format": "YYYY-MM-DD HH:mm:ss"
                },
        "prism": {
          "css": [
            "prismjs/themes/prism-dracula.css"
          ]
        }
    }
}

在这个配置文件，我使用了一些外部插件。对于这些插件，我们可以在项目的根目录下执行命令进行安装

1

gitbook install ./

搭建 github 网页

github 提供 gh-pages 功能，可以生成静态网站托管。

在github创建新仓库，默认为 master 主干枝

在本地拷贝远程仓库

1

git clone git@github.com:williamlfang/ProjectName.git

在本地仓库搭建 gitbook

1
2
3


cd ProjectName
## 开始搭建静态网页
gitbook build

建立分支 gh-pages 用于显示静态网页
1

git checkout -b gh-pages

同步拷贝 master 目录得到的 _book 到 gh-pages

1
2


git checkout master -- _book
cp -r _book/* ./

提交更新

1
2
3


git add ./*
git commit -m 'update gh-pages'
git push origin gh-pages

这样，我们便在 gh-pages 存放了生成的静态网页，通过浏览器访问可查看具体的项目网页

一键脚本

我写了一个简单的脚本 deploy.sh，实现一键执行相关的操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


#!/usr/bin/env bash

# Set the English locale for the `date` command.
export LC_TIME=en_US.UTF-8

# GitHub username.
USERNAME=williamlfang
# Name of the branch containing the Hugo source files.
SOURCE=betteR
# The commit message.
MESSAGE="Gitbook rebuild $(date)"

## -------------------------------------------
msg() {
    printf "\033[1;32m :: %s\n\033[0m" "$1"
}
## -------------------------------------------


## -------------------------------------------
## 切换到 master
git checkout master
msg "Pulling down from ${SOURCE}<master>"
#从github更新原文件并生成静态页面
# git pull

## 使用 R 制作 md
Rscript -e 'blogdown::build_dir(dir = ".", force = FALSE, ignore = "[.]Rproj$")'  2>&1 >/dev/null

msg "Rebuild gitbook"
## 安装插件
# /opt/node-v12.10.0-linux-x64/bin/gitbook install ./
## 建立静态网页
/opt/node-v12.10.0-linux-x64/bin/gitbook build

git add -A
git commit -m "update master"
git push origin master
## -------------------------------------------


## -------------------------------------------
msg "Pushing new info to gh-pages"
## 创建分支
# git checkout -b gh-pages
git checkout gh-pages
## 同步 master 的 _book 到 gh-pages
git checkout master -- _book

cp -r _book/* .
echo "node_modules
_book">.gitignore

git add -A
git commit -m "update gh-pages"
git push origin gh-pages

git checkout master
msg "We've happily done."

使用 github 发布 gitbook 电子书

安装软件

安装 gitbook

基本命令

安装插件

搭建 github 网页

一键脚本

相关内容