Build Gitbook

Build Gitbook

 Updated Blog / Gitbook6 minutes read (About 889 words)0 visits

Gitbook命令行工具，基于Markdown编写文档，后续基于Github发布该Blog

笔记的构建流程：

Chapter1 Install

安装Gitbook之前我们需要安装node.js和npm的依赖，使用npm安装gitbook

  • 首先安装Install Nodejs，Npm

    Windows：Node.js (nodejs.org)

    Linux:

    1
    2
    3
    4
    5
    6
    # add & update apt source before install nodejs.
    curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
    sudo apt-get update

    # install nodejs after that.
    sudo apt-get install -y nodejs

  • 然后安装gitbook

    1
    2
    3
    4
    5
    npm install gitbook-cli -g 

    gitbook fetch beta # 安装历史版本
    gitbook ls-remote # 列举可以下载的版本

  • 检查Gitbook版本

    1
    gitbook -V

安装Gitbook插件

安装插件主要有两种方式：一种是直接通过book和gitbook的安装来实现，另一种是基于Npm预先安装

1
npm install gitbook-plugin-PACKAGE

基于book的安装方式

插件和相关的配置在book.json中指定，关键词plugins & pluginsConfig为对应的插件的配置信息

添加插件通过修改book.json如下：

1
2
3
4
5
6
7
8
9
{
	"plugins": [
        "-summary","-katex","mathjax-pro","anchor-navigation-ex-toc",
        "search-plus","-lunr","-search","splitter","copy-code-button","github",
        "theme-comscore","-latex-codecogs","tbfed-pagefooter","-expandable-chapters-small",
        "-edit-link-plus","expandable-chapters","pageview-count","-editlink",
        "lightbox","-highlight","prism","disqus"
    ],
}

添加完新的插件配置之后，运行gitbook install ./来安装新的插件

gitbook-plugin-mathjax-pro - npm (npmjs.com)；PrismJS/prism-themes: A wider selection of Prism themes (github.com)

1
2
3
4
# gitbook-plugin-mathjax-pro 安装方式
npm install mathjax@2.7.7
npm install gitbook-plugin-mathjax-pro
# and editor the book.json as below
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
{
    "author": "AikenHong",
    "title": "Aiken's Blogs",
    "language": "zh-hans",
    "plugins": [
        "-summary","-katex","mathjax-pro","anchor-navigation-ex-toc",
        "search-plus","-lunr","-search","splitter","copy-code-button","github",
        "theme-comscore","-latex-codecogs","tbfed-pagefooter","-expandable-chapters-small",
        "-edit-link-plus","expandable-chapters","pageview-count","-editlink",
        "lightbox","-highlight","prism","disqus"
    ],
    "pluginsConfig": {
        "insert-logo":{
            "url": "https://picture-bed-001-1310572365.cos.ap-guangzhou.myqcloud.com/imgs/img/20210927180958.png",
            "style": "background: none; max-height: 120px; min-height: 120px"
        },
        "github":{
            "url": "https://aikenh.github.io/about/"
        },
        "tbfed-pagefooter": {
            "copyright":"&copy AikenHong",
            "modify_label": "该文件修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "mathjax-pro":{
            "version": "2.7.7"
        },
        "prism":{
            "css": [
                "prismjs/themes/prism-tomorrow.css"
            ],
            "lang":{
                "flow": "typescript"
            }
        },
        "disqus":{
            "shortName": "aikensdoc"
        }
        
    }
}

安装Disqus的时候，要到Disqus官网进行账号注册，并安装个人评论的网站，记录唯一的个人标识符，然后再配置中引入即可；

使用prism代替

Chapter2 Configure

gitbook init会初始化文件目录，文件夹会包含如下的结构：目录中的文件对应有如下的作用

1
2
3
4
5
6
7
8
9
10
11
.
├── _book         # 自动生成的html
├── book.json     # 配置文件
├── README.md     # 电子书的前言或者简介
├── SUMMARY.md    # 电子书的目录
├── chapter-1/
|   ├── README.md # 章节的描述
|   └── something.md
└── chapter-2/ 
    ├── README.md # 章节的描述
    └── something.md

编辑对应的SUMMARY同时可以按照文件夹结构进行组织，基本的组织结构可以按照下面的来进行部署

1
2
3
4
5
6
7
8
9
# 概要

* [卷 I](part1/README.md)
    * [写作很棒](part1/writing.md)
    * [GitBook很酷](part1/gitbook.md)
  
* [卷 II](part2/README.md)
    * [期待反馈](part2/feedback_please.md)
    * [更好的写作工具](part2/better_tools.md)

Chapter3 Deploy

在本地部署和运行一个样本书，设置gitbook的配置文件

初始化

将书籍创建到当前的目录或者指定的目录中

1
2
gitbook init
gitbook init ./directory # 在指定的目录中生成

构建

使用下面的命令会在当前目录下或者指定目录里生成_book目录，里面的内容是静态站点的资源文件：

1
gitbook build

Debugging

您可以使用选项 --log=debug 和 --debug 来获取更好的错误消息（使用堆栈跟踪）。例如：

1
gitbook build ./ --log=debug --debug

启动服务

使用下列服务在LocalHost可以预览我们的的本地书籍

1
gitbook serve

Chapter4 Publish

希望可以不借助gitbook服务来可视化界面，全靠git & cmd & github来进行一系列操作，这样就能通过我的onedrive来进行比较好的统一管理

托管到Github Pages

optional: 创建username.github.io的个人repo,可以通过jekyll来init该githubpage

  • 创建note’s repo, 用来存储自己的所有Liture
  • 调用gitbook serve之后将_book的文件推送到repo的gh-pages分支
  • 就可以在下列的url中看到自己的文档：aikenh.github.io/REPONAME/
  • 修改io文件夹中的_layout中的Default.html如下
    1
    <a href="https://aikenh.github.io/Docs/">Blog</a>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# enter the right dir
# we need to excute gitbook serve int terminal first
cd _book

# using condtional rules to control the update actions
if [ -d ".git" ];then
  echo "exist git files"
else
  git init
fi

# update those blogs using git
git add . 
git commit -m "update those blogs"
echo "update the local git log"

# push the update to the remote repo
git remote add origin git@github.com:AikenH/Docs.git
git push -f origin master:gh-pages
echo "finish pushing files"

Reference

Build Gitbook

http://aikenh.cn/cn/Gitbook/

Author

AikenH

Posted on

2021-09-26

Updated on

2023-10-30

Licensed under

 

Like this article? Support the author with

Comments

Follow

Catalogue

Recents

×