gitbook使用教程

1. 說明

gitbook網站是一個簡單的我的在線書籍網站，在這裏能夠把本身的文檔整理成書籍發佈出來，便於閱讀。
gitbook網站：https://legacy.gitbook.com/

本文主要講解在gitbook網站上發佈一個書籍文檔和使用gitbook提供的工具在本地開發一個書籍文檔部署到本身的服務上

在此以前你須要會以下準備：

• 帳號： github有帳號，gitbook使用github帳號註冊
• git：代碼管理工具
• Markdown：gitbook主要使用MD語法來編寫書籍的
• gitbook工具：若是你在本地開發須要安裝此插件，下面有介紹
• nodejs環境：gitbook插件須要的運行環境
• 一款Markdown編輯器：方便本地開發，推薦Typora或gitbook本身的編輯器gitbook editor

2. 在gitbook網站上建立一本文檔書籍

此種方式是使用github網站加gitbook網站的方式來建立書籍的。
首先你要有一個github帳號，而後在github網站中建立了一個repo倉庫，用於存放書籍內容的倉庫。
注意：gitbook網站有時須要使用代理才能打開。

2.1 登錄gitbook網站

gitbook網站支持直接使用github帳號登錄的，推薦直接使用github帳號登錄。
打開gitbook網站：https://legacy.gitbook.com/
點擊右上角的Sign In登錄，而後選擇Sign in with GitHub選擇使用github帳號進行登錄。
第一次登錄gitbook網站時，須要github網站的認證，還須要到註冊github網站的郵箱中點擊確認。

2.2 建立一本書

2.2.1 點擊新建一本書按鈕

登錄網站後，點擊右上角的用戶圖標，而後選擇Your Profile。而後就會在右上角看見+ new按鈕，點擊此按鈕就是建立一本書。

或者在gitbook的dashboard頁面有一個New Book按鈕，點擊也能夠建立一個書籍：

或者打開此連接，直接進入建立書籍頁面：https://legacy.gitbook.com/new

2.2.2 在建立書籍中選擇github

進入新建頁面後，在左邊找到GITHUB選項。
第一次須要點擊右邊的install github integration。
此時會跳轉到github頁面去安裝這個插件，能夠選擇全部倉庫或者某個倉庫，而後點擊install安裝,輸入github密碼後完成安裝。
此時回到gitbook新建頁面刷新，選擇github後，會在右邊會出現以下選項：

• title ： 書籍的標題
• description：對這本書的描述
• Select a Repository: 選擇github中的倉庫等
• Public or Private: 這本書是公開(Public)仍是私有(Private)的

選項填好後，而後點擊create book按鈕。

注意：標題必定要是英文的，由於這要做爲這本書籍的連接（建立成功後可修更名稱）。

點擊create book按鈕後，會出現這本書籍頁面，而後刷新頁面，而後點擊ABOUT。

而後點擊右邊的Read按鈕便可閱讀。

進入閱讀後以下效果：

此時一本書籍已經在gitbook上建立完畢了。

2.3 建立書籍目錄文件

通過上面的步驟後，只是建立了一本書籍，可是此時還不完整，由於缺乏了書籍的目錄。
首先須要在項目的根目錄建立一個SUMMARY.md文件，此文件就是gitbook的目錄，內容格式以下：

* [說明](README.md)
* HTML
  - [測試鏈接1](/doc/a.md) 
* JAVASCRIPT
  - [b文件](/javascript/b.md)

此時項目目錄結構：

.
├── README.md
├── SUMMARY.md
├── doc
│   └── a.md
└── javascript
    └── b.md

保存SUMMARY.md後，提交內容到github網站倉庫中，須要等待一會才能在gitbook網站上看見更新內容，有時須要等好久才能更新，最終效果以下圖所示：

3. 使用gitbook工具開發

上面說的在gitbook網站發佈一本書雖然方便，可是有以下缺點：

一、gitbook網站常常打不開，須要使用代理才能訪問
二、修改提交後有時須要好久才能顯示更新

還好，gitbook還提供了基於Node.js的命令行工具，可以使用 Github/Git 和 Markdown 來製做精美的電子書,而後部署到本身的網站上(或在github託管)。

gitbook命令行工具首先須要本地電腦有nodejs和終端。
通常linux系統和Mac系統自帶nodejs和終端，Windows系統須要安裝nodejs和終端。
windows系統推薦cmder終端,安裝和介紹請自行查找。
可以使用以下命令在終端查看系統是否有nodejs：

node -v
v8.12.0

若是出現版本號，那麼說明已經安裝了，若是沒找到這個命令，那麼進入node官網：http://nodejs.cn/ ，選擇下載，選擇對應的操做系統後下載安裝便可。

gitbook命令行工具推薦nodejs版本要v4.0.0以上，若是版本太低，可看以下教程將版本升級到v4.0.0以上：
https://segmentfault.com/a/11...

3.1 安裝gitbook-cli工具

gitbook-cli是一個在同一系統上安裝和使用多個版本的GitBook的實用程序。它將自動安裝所需版本的GitBook來構建一本書。
打開終端輸入npm install gitbook-cli -g命令進行全局安裝：

npm install gitbook-cli -g

npm http fetch GET 304 https://registry.npm.taobao.org/os-tmpdir 100ms (from cache)
npm http fetch GET 304 https://registry.npm.taobao.org/os-homedir 113ms (from cache)
/usr/local/bin/gitbook -> /usr/local/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 17.806s

安裝成功後可以使用gitbook --version來查看是否安裝成功：

gitbook --version
CLI version: 2.3.2
GitBook version: 3.2.3

注意：終端第一次運行gitbook命令，可能會自動安裝gitbook，由於剛纔安裝的是CLI，此時CLI會自動安裝gitbook。

若是想卸載CLI，可以使用npm uninstall gitbook-cli -g來刪除。

3.2 初始化一本書

初始化一本書的命令是gitbook init,

首先在終端建立一個項目目錄，並進入這個目錄：

mkdir book
cd book

而後使用gitbook init來初始化一本書：

~ gitbook init

warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished

gitbook init會在空項目中建立README.md和SUMMARY.md兩個文件：
README.md文件是項目的介紹文件。
SUMMARY.md是gitbook書籍的目錄。

若是SUMMARY.md文件裏面有以下內容：

* [項目介紹](README.md)
* http
    * [http說明](doc/http/http解析.md)
        * [tcp說明](doc/http/tcp/tcp說明.md)
            * [udp說明](doc/http/tcp/udp/udp說明.md)
* HTML
    * [HTML5-特性說明](doc/html/HTML5-特性說明.md)

那麼在使用gitbook init時，若是目錄裏面的文件不存在，則會建立目錄中的文件：

~ gitbook init

info: create doc/http/http解析.md 
info: create doc/http/tcp/tcp說明.md 
info: create doc/http/tcp/udp/udp說明.md 
info: create doc/html/HTML5-特性說明.md 
info: create SUMMARY.md 
info: initialization is finished

3.3 本地啓動服務編寫書籍

終端打開項目目錄，使用gitbook serve啓動服務：

~ 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 "theme-default"... OK 
info: found 5 pages 
info: found 0 asset files 
info: >> generation finished with success in 2.1s ! 

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

而後根據終端的提示，在瀏覽器中打開http://localhost:4000查看書籍，效果以下圖所示：

注意：gitbook serve命令會在項目中生成一個_book的文件夾,此文件夾就是最終生成的項目。

3.4 文檔打包

可以使用gitbook build命令來生成最終的項目：

~ 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 5 pages 
info: found 0 asset files 
info: >> generation finished with success in 1.0s !

命令執行結束後，會在項目下生成_book的文件夾,此文件夾就是最終生成的項目。
在_book文件夾裏有一個index.html文件，這個文件就是文檔網站的HTM入口，把_book文件夾複製到服務器，而後把web服務的入口引向index.html便可完成文檔網站的部署。

若是你想查看輸出目錄詳細的記錄，可以使用gitbook build ./ --log=debug --debug來構建查看。

3.5 生成電子書

這裏本人試了，沒有成功，你能夠嘗試一下

GitBook 能夠生成一個網站，但也能夠輸出內容做爲電子書（ePub，Mobi，PDF）。

# Generate a PDF file
$ gitbook pdf ./ ./mybook.pdf

# Generate an ePub file
$ gitbook epub ./ ./mybook.epub

# Generate a Mobi file
$ gitbook mobi ./ ./mybook.mobi

我還在網上找了一個包：https://www.npmjs.com/package... ，能夠試一下

3.6 項目部署到GitHub Pages

這部分須要使用git和github網站，若是你不會，請自行在網上搜索文檔查看。

因爲gitbook生成的項目跟文檔的源碼是兩個部分，因此能夠把文檔放到master分支上，部署的網站放到gh-pages 分支。

3.6.1 在github上建立一個倉庫

這個倉庫用於存放你編寫的項目，和部署項目，如何建立請自行查找。

3.6.2 本地項目提交到github倉庫

在項目中建立一個.gitignore文件，內容以下：

# 忽略gitbook生成的項目目錄
_book

而後終端打開項目，輸入以下命令,來提交文檔項目到github上：

~ git init
~ git add .
~ git commit -m '初始化gitbook本地項目'
~ git remote add origin https://github.com/yulilong/book.git 
~ git push -u origin master

上面命令執行結束後，就會把代碼提交到github上的倉庫。
注意倉庫地址要替換成你本身的連接。

3.6.3 生成項目並上傳到github倉庫的gh-pages分支

因爲打包命令太多，爲了簡單化，如今寫一個腳本命令來自動執行。固然你也能夠終端本身執行這些命令。

爲了部署方便，能夠建立一個腳本文件deploy.sh,內容以下：

#!/usr/bin/env sh

echo '開始執行命令'
# 生成靜態文件
echo '執行命令：gitbook build .'
gitbook build .

# 進入生成的文件夾
echo "執行命令：cd ./_book\n"
cd ./_book

# 初始化一個倉庫，僅僅是作了一個初始化的操做，項目裏的文件尚未被跟蹤
echo "執行命令：git init\n"
git init

# 保存全部的修改
echo "執行命令：git add -A"
git add -A

# 把修改的文件提交
echo "執行命令：commit -m 'deploy'"
git commit -m 'deploy'

# 若是發佈到 https://<USERNAME>.github.io/<REPO>
echo "執行命令：git push -f https://github.com/yulilong/book.git master:gh-pages"
git push -f https://github.com/yulilong/book.git master:gh-pages

# 返回到上一次的工做目錄
echo "回到剛纔工做目錄"
cd -

注意腳本文件代碼中倉庫地址要替換成你本身的地址。

文件保存後，在終端執行以下命令開始把最終項推送到gh-pages分支：

bash deploy.sh

執行成功後，打開你的github倉庫，而後選擇branch分支，會發現多了一個gh-pages分支，打開這個分以後，裏面會有一個index.html文件。說明部署的代碼上傳成功了。
注意：若是沒有gh-pages分支說明沒有部署成功請查看剛纔執行的終端看哪裏報錯了，解決報錯直到成功部署。

3.6.4 配置GitHub Pages顯示網站

在github網站上的倉庫裏面點擊Settings -> GitHub Pages選項中 -> Source裏面選擇gh-pages branch 而後點擊Save按鈕，而後在GitHub Pages下面就會看見一個網址，這個網址就是最終的網站。
最終效果以下圖所示：

3.7 一些部署到GitHub Pages的例子

https://github.com/yodaos-pro...

http://gitbook.zhangjikai.com...

4. gitbook的配置文件講解

若是你想對你的網站有更詳細的個性化配置或使用插件，那麼須要使用配置文件。
配置文件寫完後，須要重啓服務或者從新打包才能應用配置。
gitbook的配置文件名是book.json，首先在項目的根目錄中建立book.json文件。
book.json主要內容：

{
    "title": "個人一本書",
    "author" : "yu",
    "description" : "我第一本書的描述，很好",
    "language" : "zh-hans",
    "structure": {
        "readme": "introduction.md"
    },
    "plugins": [
        "-lunr",
        "-search",
        "search-pro",
        "back-to-top-button"
    ],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "isShowTocTitleIcon": true
        }
    },
    "links" : {
        "sidebar" : {
            "個性連接1" : "https://www.baidu.com",
            "個性連接2" : "https://www.baidu.com"
        }
    },
    "styles": {
        "website": "styles/website.css",
        "ebook": "styles/ebook.css",
        "pdf": "styles/pdf.css",
        "mobi": "styles/mobi.css",
        "epub": "styles/epub.css"
    }
}

更多的配置參數：https://github.com/GitbookIO/...

4.1 book.json中一些主要參數說明

• title
  標題
• author
  做者
• description
  描述，對應gitbook網站的description
• language
  使用的語言，zh-hans是簡體中文，會對應到頁面的<html lang="zh-hans" >

• structure
  指定 Readme、Summary、Glossary 和 Languages 對應的文件名，下面是這幾個文件對應變量以及默認值：

  Variable	Description
  structure.readme	Readme file name (defaults to README.md)
  structure.summary	Summary file name (defaults to SUMMARY.md)
  structure.glossary	Glossary file name (defaults to GLOSSARY.md)
  structure.languages	Languages file name (defaults to LANGS.md)

  好比想把readme文件個名字，則可使用以下配置

  "structure": {
      "readme": "introduction.md"
  },

  使用這個配置後，gitbook服務就不會找readme文件，而去找introduction文件當項目說明，這樣就能夠把readme文件徹底當成代碼倉庫說明文檔了。

• plugins
  使用的插件列表，全部的插件都在這裏寫出來，而後使用gitbook install來安裝。
• pluginsConfig
  插件的配置信息，若是插件須要配置參數，那麼在這裏填寫。

• links
  目前能夠給側導航欄添加連接信息

  "links" : {
      "sidebar" : {
          "個性連接1" : "https://www.baidu.com"
      }
  }

• styles
  自定義頁面樣式，各類格式對應各自的css文件

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

4.1 配置默認主題

默認的主題能夠經過配置來作一下效果。
好比側邊欄菜單顯示標題數字，能夠在配置文件的pluginsConfig參數中寫入以下字段：

{
    "pluginsConfig": {
        "theme-default": {
            "showLevel": true
        }
    }
}

效果以下圖：

5. gitbook的一些實用插件

gitbook插件能夠解決一些網站不太方便的地方，如側邊欄導航不能收縮，自帶搜索不支持中文等。
用了插件書籍網站會更靈活和美觀。

因爲插件不少，請參考個人另外一篇文章：https://segmentfault.com/a/11...

參考資料

gitbook 的配置文件book.json說明
gitbook工具文檔
GitBook Editor
gitbook 評論插件
Gitbook 使用教程
gitbook 實用插件