使用gitbook - xiaohuochai－IT工程師數位筆記本

文章出處

前面的話

　　gitbook功能強大，可以自動實現搜索及翻頁等功能，上手容易，用markdown書寫即可，且可以自動生成響應式網站。本文將詳細介紹如何使用gitbook

安裝

　　1、使用npm全局安裝gitbook-cli

npm install gitbook-cli -g

　　2、使用gitbook --version來查看gitbook的版本

gitbook --version

　　3、接下來對gitbook進行基礎配置，創建并進入一個筆記文件夾

mkdir myNote
cd myNode

　　4、初始化gitbook，會自動生成兩個文件。README.md用于書籍介紹，SUMMARY.md用于設置書籍的目錄

gitbook init

　　5、接著，使用gitbook serve命令來啟動gitbook本地服務器，預覽默認的書籍內容

gitbook serve

　　6、打開localhost:4000，會出現如下頁面

　　7、使用gitbook install命令來安裝插件

gitbook install

　　8、生成靜態網頁

　　使用gitbook build命令，gitbook把md文件構建成靜態網頁

gitbook build #生成靜態網頁

目錄結構

　　GitBook 基本的目錄結構如下所示

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

【book.json】

　　該文件用于存放配置信息

【Glossary.md】

　　允許指定要顯示為注釋的術語及其各自的定義。根據這些條款，GitBook將自動構建一個索引并突出顯示這些術語

　　該GLOSSARY.md格式是列表h2的標題，以及描述項一起

## Term
Definition for this term

## Another term
With it's definition, this can contain bold text
and all other kinds of inline markup ...

【README.md】

　　書本的第一頁內容是從文件 README.md 中提取的。如果這個文件名沒有出現在 SUMMARY 中，那么它會被添加為章節的第一個條目

【.bookignore】

　　GitBook將讀取.gitignore，.bookignore以及.ignore文件以獲得文件和文件夾跳過列表

【SUMMARY.md】

　　該文件用于存放GitBook的文件目錄信息，左側的目錄就是根據這個文件來生成的，默認對應的文件是 SUMMARY.md，可以在 book.json 重新定義該文件的對應值。它通過Markdown中的列表語法來表示文件的父子關系

　　[注意]不被SUMMARY.md包含的文件不會被gitbook處理.

　　該文件基本的寫法如下

# Summary

* [Part I](part1/README.md)
    * [Writing is nice](part1/writing.md)
    * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
    * [We love feedback](part2/feedback_please.md)
    * [Better tools for authors](part2/better_tools.md)

　　目錄中的章節可以使用錨點指向文件的特定部分

# Summary

### Part I

* [Part I](part1/README.md)
    * [Writing is nice](part1/README.md#writing)
    * [GitBook is nice](part1/README.md#gitbook)
* [Part II](part2/README.md)
    * [We love feedback](part2/README.md#feedback)
    * [Better tools for authors](part2/README.md#tools)

　　目錄可以分為以標題或水平線分隔的部分

# Summary

### Part I

* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)

### Part II

* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)

----

* [Last part without title](part3/title.md)

配置

　　下面是book.json中的一些配置信息

【title】

　　書本的標題

"title" : "小火柴的前端小冊子"

【author】

　　作者的相關信息

"author" : "xiaohuochai"

【description】

　　本書的簡單描述

"description" : "小火柴的前端學習記錄"

【language】

　　Gitbook使用的語言

"language" : "zh-hans",

【root】

　　指定存放 GitBook 文件（除了 book.json）的根目錄

　　如果目錄結構如下

.
├── book.json
└── docs/
    ├── README.md
    └── SUMMARY.md

　　則可以這樣設置

"root": "./docs"

【structure】

　　指定自述文件，摘要，詞匯表等的路徑

變量   　　　　　　　　 描述
structure.readme     自述文件名（默認為README.md）
structure.summary    摘要文件名（默認為SUMMARY.md）
structure.glossary   詞匯表文件名（默認為GLOSSARY.md）
structure.languages  語言文件名（默認為LANGS.md）

【variables】

　　可以通過{{book.value}}來獲取變量，變量會從書本內容中尋找對應的值

     "variables": {
        "value": "Hello World"
    }

【link】

　　插件中的鏈接(null: default, false: remove, string: new value)

  "links": {
        // Custom links at top of sidebar
        "sidebar": {
            "Custom link name": "https://xiaohuochai.site"
        },
        // Sharing links
        "sharing": {
            "google": null,
            "facebook": null,
            "twitter": null,
            "weibo": null,
            "all": null
        }
    }

插件

plugins　　        要加載的插件列表
pluginsConfig　  插件配置

　　gitbook默認帶有6個插件

highlight
search
sharing
font-settings
livereload
lunr

　　如果要去除自帶的插件，可以在插件名稱前面加-

"plugins": [
    "-search"
]

　　下面來介紹一些常用的插件

【打賞功能：donate】

{
    "plugins": ["donate"],
    "pluginsConfig": {
        "donate": {
          "wechat": "例：/images/qr.png",
          "alipay": "http://blog.willin.wang/static/images/qr.png",
          "title": "默認空",
          "button": "默認值：Donate",
          "alipayText": "默認值：支付寶捐贈",
          "wechatText": "默認值：微信捐贈"
        }
    }
}

【中文搜索：search-plus】

{
    plugins: ["-lunr", "-search", "search-plus"]
}

【廣告功能：ad】

{
  "plugins": ["ad"],
  "pluginsConfig": {
    "ad": {
      "contentTop": "<div>Ads at the top of the page</div>",
      "contentBottom": "%3Cdiv%3EAds%20at%20the%20bottom%20of%20the%20page%3C/div%3E"
    }
  }
}

// note: contentBottom is escape('<div>Ads at the bottom of the page</div>')

【目錄寬度可調節：splitter】

{
    "plugins": ["splitter"]
}

【github圖標】

{
    "plugins": [ "github" ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/your/repo"
        }
    }
}

【自定義頁腳：tbfed-pagefooter】

{
    "plugins": [ "tbfed-pagefooter" ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
             "copyright":"&copy Taobao FED Team",
             "modify_label": "該文件修訂時間：",
             "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

【目錄章節可折疊：expandable-chapters】

{
    {
        plugins: ["expandable-chapters"]
    }
    {
        "pluginsConfig": {
            "expandable-chapters":{}
        }
    }
}

【暢言評論：changyan】

{
    "plugins": [
        "changyan"
    ],
    "pluginsConfig": {
        "changyan": {
            "appid": "your changyan's appid",
            "conf": "the conf in the code generate by changyan"
        }
    }
}

【返回頂部：back-to-top-button】

{
    "plugins" : [ "back-to-top-button" ]
}

【更換ico：favicon】

　　[注意]favicon只支持本地路徑，不支持網絡路徑

{
    "plugins": [
        "favicon"
    ],
    "pluginsConfig": {
        "favicon": {
            "shortcut": "assets/images/favicon.ico",
            "bookmark": "assets/images/favicon.ico",
            "appleTouch": "assets/images/apple-touch-icon.png",
            "appleTouchMore": {
                "120x120": "assets/images/apple-touch-icon-120x120.png",
                "180x180": "assets/images/apple-touch-icon-180x180.png"
            }
        }
    }
}

主題

　　目前 GitBook 提供了三類文檔： Book 文檔、API文檔、FAQ文檔。常用的是 Book 文檔模式，如果需要使用 API 文檔模式或者 FAQ 文檔模式，只需引入文檔對應的主題插件即可

【Book】

　　Book 是常用的模式，大部分插件也都是針對這個模式做的。

　　theme-default 是默認的 Book 主題。將 showLevel 設為 true，就可以顯示標題前面的數字索引，默認不顯示

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

　　them-comscore是另一個Book主題，可以為標題添加顏色

{
"plugins": [
        "theme-comscore"
    ]
}

【API】

　　GitBook 同樣可以編寫 API 文檔，只需要引入 theme-api 插件，引入之后會替換默認的樣式

{
    "plugins": ["theme-api"],
    "pluginsConfig": {
        "theme-api": {
            "theme": "dark"
        }
    }
}

【FAQ】

　　theme-faq 插件主要用來制作知識庫或者幫助中心，GitBook 的幫助中心就是使用的該主題。為了支持中文搜索需要引入 search-pro 包

{
    "plugins": [
        "theme-faq",
        "-lunr",
        "search-pro@^2.0.2"
    ]
}

　　編寫幫助中心很簡單，在 Summary 里配置問題以及答案所在的文件，在對應文件中寫入問題的答案即可

　　[注意]由于FAQ主題默認會調用maxcdn里的bootstrap和fontawesome，所以對于國內用戶來說，可訪問性不是很好

# Summary

## HTML
* [介紹](README.md)
* [語法介紹](introduce.md)
* [結構](struct.md)

## HTTP
*  [HTTP](HTTP.md)

## CSS
* [display](display.md)
* [float](float.md)
* [absolute](absolute.md)
* [relative](relative.md)

修改內容

　　下面在初始化的gitbook的基礎上修改內容，并制作一個簡單的電子書

　　[注意]gitbook需要掌握markdown語法，詳細信息移步至此

　　修改目錄文件SUMMARY.md

# Summary

* [前言](README.md)
* [HTML](HTML.md)
* [CSS](CSS.md)
* [JS](JS.md)
* [ES6](ES6.md)
* [HTTP](HTTP.md)
* [前端框架](FELib.md)
    * [Bootstrap](bs.md)
    * [jQuery](jq.md)
    * [Vue](vue.md)
* [前端構建](build.md)
* [版本管理](version.md)
* [后端相關](BELib.md)
    * [PHP](php.md)
    * [MySQL](mysql.md)
    * [NodeJS](node.md)
    * [MongoDB](mongo.md)
* [服務器端](server.md)
* [輔助工具](helper.md)
* [術語表](Glossary.md)
* [參考資料](Resources.md)

　　修改book.json文件

{
  "title": "FE-booklet",
  "description": "小火柴的前端小冊子",
  "author": "xiaohuochai",
  "language": "zh-hans",
  "links": {
    "sidebar": {
      "小火柴的博客": "https://webhuochai.com"
    }
  },
  "styles":{
    "website":"style.css"
  },
  "variables": {
    "cdn": "://static.xiaohuochai.site/"
  },
  "plugins": [
    "-lunr",
    "-search",
    "-livereload",
    "-sharing",
    "expandable-chapters",
    "search-plus",
    "splitter",
    "github",
    "tbfed-pagefooter","back-to-top-button",
  ],
  "pluginsConfig": {
    "github": {
      "url": "https://github.com/littlematch0123/FE-booklet"
    },
    "tbfed-pagefooter": {
      "copyright": "&copy; xiaohuochai",
      "modify_label": "文件修訂時間：",
      "modify_format": "YYYY-MM-DD HH:mm:ss"
    },
  }
}