【Tools】GitBook簡明教程

00. 目錄

文章目錄

01. GitBook簡介

GitBook是一個使用 Git 和 Markdown 來構建書籍的工具。它可以將你的書輸出很多格式：PDF，ePub，mobi，或者輸出爲靜態網頁。
GitBook工具鏈是開源並且完全免費的，它的源碼可以在 GitHub 上獲取。

02. GitBook安裝

2.1 安裝npm工具

deng@itcast:~$ sudo apt install npm

2.2 安裝GitBook

deng@itcast:~$ sudo npm install gitbook-cli -g

2.3 驗證是否安裝成功

deng@itcast:~$ gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3

03. GitBook使用

3.1 GitBook初始化

打開一個文件夾 test使用 gitbook init 初始化文件夾，會自動生成兩個必要的文件 README.md 和 SUMMARY.md

deng@itcast:~/test$ gitbook init
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished 
deng@itcast:~/test$

文件	說明
README.md	書的介紹文字，如前言、簡介，在章節中也可做爲章節的簡介。
SUMMARY.md	定製書籍的章節結構和順序。

README.md 和 SUMMARY.md 是 GitBook 製作電子書的必要文件。

3.2 GitBook預覽

方式一：通過網絡訪問

deng@itcast:~/test$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.3s ! 

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

在瀏覽器輸入http://ip:4000

[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片保存下來直接上傳(img-6NQWiroc-1593573700671)(assets/image-20200701101235013.png)]

方式二：生成靜態頁面

deng@itcast:~/test$ gitbook build
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.4s ! 
deng@itcast:~/test$

生成.html靜態文件，配置後可以直接訪問預覽

04. GitBook命令

GitBook命令都可以通過shell或者cmd環境下執行。

4.1 安裝命令

deng@itcast:~/test$ npm install gitbook-cli -g

4.2 初始化命令

初始化新建一個文件夾，例如新建 test，然後在該目錄下執行命令

deng@itcast:~/test$ gitbook init

會自動生成兩個必要的文件 README.md 和 SUMMARY.md。

4.3 預覽命令

deng@itcast:~/test$ gitbook serve

gitbook會啓動一個4000端口用於預覽，可以在瀏覽器打開網址： http://localhost:4000 預覽效果。

4.4 編譯命令

deng@itcast:~/test$ gitbook build

運行該命令後會在根文件夾生成一個 book 文件夾，包含了書籍的所有 html 文件. 可以使用該命令來生成網頁而不開啓服務器，也可以將book文件夾部署到服務器上。

4.5 help命令

deng@itcast:~/test$ gitbook --help

Usage: gitbook [options] [command]

輸出gitbook的幫助信息

4.6 serve命令

deng@itcast:~/test$ gitbook serve

生成靜態網頁並運行服務器

4.7 build命令

deng@itcast:~/test$ gitbook build

生成靜態網頁

deng@itcast:~/test$ gitbook build --gitbook=3.2.3

生成靜態網頁時指定gitbook的版本，如果本地沒有將先下載

deng@itcast:~/test$ gitbook build --log=debug

指定log級別

deng@itcast:~/test$ gitbook build --debug

輸出錯誤信息

4.8 ls命令

deng@itcast:~/test$ gitbook ls
GitBook Versions Installed:

    * 3.2.3

Run "gitbook update" to update to the latest version.
deng@itcast:~/test$

列出所有的gitbook版本

4.9 ls-remote命令

deng@itcast:~/test$ gitbook ls-remote

列出遠程可用的gitbook版本

4.10 update命令

deng@itcast:~/test$ gitbook update

更新到gitbook的最新版本

4.11 uninstall命令

deng@itcast:~/test$ gitbook uninstall 3.2.3

卸載對應的gitbook版本

4.12 install命令

deng@itcast:~/test$ gitbook install

安裝依賴

05. GitBook配置

變量	描述
root	包含所有圖書文件的根文件夾的路徑，除了 book.json
structure	指定自述文件，摘要，詞彙表等的路徑，參考 Structure paragraph.
title	您的書名，默認值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預填的。
description	您的書籍的描述，默認值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預填的。
author	作者名。在GitBook.com上，這個字段是預填的。
isbn	國際標準書號 ISBN
language	本書的語言類型 —— ISO code 。默認值是 en
direction	文本閱讀順序。可以是 rtl （從右向左）或 ltr （從左向右），默認值依賴於 language的值
gitbook	應該使用的GitBook版本。使用 SemVer 規範，並接受類似於 “> = 3.0.0” 的條件。

root

包含所有圖書文件的根文件夾的路徑， book.json 文件除外。

"root" : "./docs"

structure

指定 Readme、Summary、Glossary 和 Languages 對應的文件名。

title

電子書的書名，默認值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預先填寫的。

"title" : "gitbook-notes"

description

電子書的描述，默認值是從 README 中提取出來的。在GitBook.com上，這個字段是預先填寫的。

"description" : "C++教程"

author

作者姓名，在GitBook.com上，這個字段是預先填寫的

"author" : "Ming Li"

direction

文本的方向。可以是 rtl 或 ltr，默認值取決於語言的值。

"direction" : "ltr"

gitbook

應該使用的GitBook版本。使用SemVer規範，接受類似於 >=3.0.0 的條件。

"gitbook" : "3.0.0",
"gitbook" : ">=3.0.0"

language

Gitbook使用的語言, 版本2.6.4中可選的語言如下： en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw

"language" : "zh-hans",

links

在左側導航欄添加鏈接信息

"links" : {
    "sidebar" : {
        "Home" : "https://github.com/json/gitbook-notes"
    }
}

styles

自定義頁面樣式，默認情況下各generator對應的css文件

"styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
}

例如要使 h1、h2 標籤有下邊框，可以在 website.css 中設置

h1 , h2{
    border-bottom: 1px solid #EFEAEA;
}

plugins 插件列表

可以在插件前面加-符號刪除默認插件，默認五種插件如下，更多插件

highlight：代碼高亮
search：導航欄查詢功能（不支持中文）
sharing：右上角分享功能
font-settings：字體設置（最上方的"A"符號）
livereload：爲GitBook實時重新加載
pluginsConfig 配置插件的屬性

綜合實例

{
    "title": "GItBook筆記",
    "description": "GitBook筆記",
    "author": "tom",
    "output.name": "site",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "root": ".",
    "links": {
        "sidebar": {
            "首頁": "http://www.json.com"
        }
    },
    "plugins": [
        "code",
        "-search",
        "search-pro",
        "github",
        "splitter",
        "tbfed-pagefooter",
        "donate",
        "-sharing",
        "sharing-plus",
        "prism",
        "-highlight",
        "styles-less",
        "toggle-chapters",
        "multipart",
        "ancre-navigation"
    ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/json"
        },
        "code": {
            "copyButtons": true
        },
        "tbfed-pagefooter": {
            "copyright": "Copyright © lijiam 2019",
            "modify_label": "本書發佈時間：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "donate": {
            "wechat": "/assets/images/wxpay.png",
            "alipay": "/assets/images/alipay.png",
            "title": "",
            "button": "賞",
            "alipayText": "支付寶打賞",
            "wechatText": "微信打賞"
        },
        "sharing": {
            "facebook": true,
            "twitter": true,
            "weibo": true,
            "qq": true,
            "all": [
                "douban",
                "google",
                "qzone",
                "linkedin"
            ]
        },
        "prism": {
            "css": [
                "prismjs/themes/prism-solarizedlight.css"
            ],
            "lang": {
                "flow": "typescript"
            }
        }
    },
    "styles": {
        "website": "assets/styles/website.less",
        "ebook": "assets/styles/ebook.less",
        "pdf": "assets/styles/pdf.less",
        "mobi": "assets/styles/mobi.less",
        "epub": "assets/styles/epub.less"
    }
}

06. GitBook插件

在根目錄下創建book.json文件

6.1 配置

在book.json的plugins參數中添加插件名。

{
    "plugins": ["mathjax"]
}

6.2 安裝

gitbook install

#或者
npm install gitbook-plugin-插件名

6.3 重啓服務
如果使用gitbook install安裝的很慢，建議使用npm init初始化一個package.json文件，然後每個包通過npm命令安裝，以後就可以通過npm install一鍵快速安裝依賴包了。

溫馨提示：

1、插件一定先要在book.json文件裏面plugins中才能生效，如果只是安裝了插件，而沒配置的話是不會生效的。

2、gitbook命令安裝慢，而且是全部插件都安裝一遍，如果只安裝一個插件的話建議使用NPM命令安裝。

6.4 插件列表

配置使用的插件

"plugins": [
    "-search",
    "back-to-top-button",
    "expandable-chapters-small",
    "insert-logo"
]

其中-search中的 - 符號代表去除默認自帶的插件

Gitbook默認自帶有5個插件：

插件	說明
highlight	代碼高亮
search	導航欄查詢功能（不支持中文）
sharing	右上角分享功能
font-settings	字體設置（最上方的"A"符號）
livereload	爲GitBook實時重新加載

6.5 插件屬性

配置插件的屬性例如配置insert-logo的屬性：

  "pluginsConfig": {
    "insert-logo": {
      "url": "images/logo.png",
      "style": "background: none; max-height: 30px; min-height: 30px"
    }
  }

6.6 實用插件

記錄一些實用的插件用法：在book.json中添加"plugins"和"pluginConfig"字段。然後執行gitbook install，或者使用NPM安裝npm install gitbook-plugin-插件名，也可以從源碼GitHub地址中下載，放到node_modules文件夾裏（GitHub地址在進入插件地址右側的GitHub鏈接）

07. 在線文檔雲平臺

VuePress
看雲
 語雀
 BookStack
docsify
Docute
MinDoc
Wikitten
DokuWiki
MkDocs
Penflip

如果希望託管在平臺，請根據項目數量選擇使用GitBook或者看雲

如果自建，輕量級的推薦docsify，內容多推薦DokuWiki

08. 附錄

8.1 GitBook官方網站

網站：https://www.gitbook.com/

8.2 插件博客

網站：https://blog.csdn.net/fghsfeyhdf/article/details/88403548

8.3 MarkDown筆記

網站：https://www.jianshu.com/p/b03a8d7b1719

8.4 參考博客
網站：http://gitbook.hushuang.me/themes/

【Tools】GitBook簡明教程

00. 目錄

文章目錄

01. GitBook簡介

02. GitBook安裝

03. GitBook使用

04. GitBook命令

05. GitBook配置

06. GitBook插件

07. 在線文檔雲平臺

08. 附錄

一個簡單的MD5加鹽

C# 代碼學習

藍橋15屆stema編程題密碼鎖-動態規劃 C++和Python最後一道題

2021看雪SDC議題回顧 | SaTC：一種全新的物聯網設備漏洞自動化挖掘方法

Kafka存儲機制

aws語音呼叫調用，告警電話

【轉】[C#] WebAPI 防止併發調用二（冥等性）

C#/.NET/.NET Core優秀項目和框架2024年4月簡報

HTTP URL 詳解

得物 ZooKeeper SLA 也可以 99.99%

【嵌入式】C語言高級編程-長度爲0的數組(05)

【嵌入式】Ubuntu20.04執行arm-linux-gc 沒有那個文件或目錄

【嵌入式】C語言高級編程-語句表達式(03)

【嵌入式】C語言高級編程-container_of宏(04)

【嵌入式】C語言高級編程-數組和結構體初始化(02)

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結