gitbook經常使用的插件

時間  2019-11-08
標籤 gitbook 經常 使用 插件 欄目 Git 简体版
原文   原文鏈接

1. 說明

本文主要講解gitbook插件的使用。
gitbook使用教程請參考我另外一篇文章：https://segmentfault.com/a/11...css

Gitbook默認自帶有5個插件：html

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

gitbook插件能夠解決一些網站不太方便的地方，如側邊欄導航不能收縮，自帶搜索不支持中文等。node

插件安裝、使用方法：git

一、 在 book.json的plugins參數中添加插件名。
二、終端使用 gitbook install來安裝插件，或使用NPM命令來單獨安裝： npm install gitbook-plugin-插件名。
三、重啓服務或者從新打包就能看見效果。
四、若是使用 gitbook install安裝的很慢，建議使用 npm init初始化一個package.json文件，而後每一個包經過npm命令安裝，之後就能夠經過 npm install一鍵快速安裝依賴包了。

注意：
一、插件必定先要在book.json文件裏面plugins中才能生效，若是隻是安裝了插件，而沒配置的話是不會生效的。
二、gitbook命令安裝慢，並且是所有插件都安裝一遍，若是隻安裝一個插件的話建議使用NPM命令安裝。github

2. 高頻經常使用插件

2.1 search-pro 高級搜索（支持中文）

search-pro支持中文搜索，在使用此插件以前，須要將默認的search和lunr 插件去掉。
在book.json的plugins參數中添加插件名：npm

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

其中"-search"中的-符號表明去除默認自帶的插件。
而後使用npm install gitbook-plugin-search-pro --registry=https://registry.npm.taobao.org/json

2.2 左側目錄可摺疊

2.2.1 chapter-fold

支持多層目錄，點擊導航欄的標題名就能夠實現摺疊擴展。
在book.json的plugins參數中添加插件名：segmentfault

{
    "plugins": ["chapter-fold"]
}

而後使用npm install gitbook-plugin-chapter-fold命令安裝插件。
使用效果以下圖:數組

clipboard.png

注意：要想目錄摺疊，SUMMARY.md目錄應該以下：app

* [項目介紹](README.md)

* [tcp說明](doc/http/tcp/tcp說明.md)
    * [udp說明](doc/http/tcp/udp/udp說明.md)
* [html](doc/html/readme.md)
    * [HTML5-特性說明](doc/html/HTML5-特性說明.md)

以下寫法會產生bug，致使CSS是收縮的，不能展開，效果如上面的動圖：

* CSS 
    * [說明](doc/css/readme.md)

2.2.2 expandable-chapters

這個插件也是左側目錄摺疊的插件，不一樣的是能夠解決chapter-fold插件的bug，怎麼寫都會摺疊目錄
在book.json的plugins參數中添加插件名：

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

安裝命令：npm install gitbook-plugin-expandable-chapters
注意：這個插件也有問題，就是以下寫法的，須要點擊箭頭才能展開收縮菜單：

* [tcp說明](doc/http/tcp/tcp說明.md)
    * [udp說明](doc/http/tcp/udp/udp說明.md)

解決的辦法是和chapter-fold插件一塊兒用，互補一下各自的問題就完美解決了：

"plugins": [
    "expandable-chapters",
    "chapter-fold",
]

注意還有一個expandable-chapters-small插件也是摺疊菜單的，可是這個插件跟chapter-fold有同樣的bug，這裏就不講了，用上面兩個插件就完美解決問題了。

2.3 splitter 側邊欄寬度可調節

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

{
    "plugins": ["splitter"]
}

而後使用npm install gitbook-plugin-splitter命令安裝插件。
使用效果以下圖:
clipboard.png

2.4 生成頁內目錄

2.4.1 page-treeview 在頁面頂部顯示目錄

不須要插入標籤，能支持到6級目錄，在頁面頂部顯示。
在book.json的plugins參數中添加插件名：

{
    "plugins": ["page-treeview"],
    "pluginsConfig": {
        "page-treeview": {
            "copyright": "Copyright © aleen42",
            "minHeaderCount": "2",
            "minHeaderDeep": "2"
        }
    }
}

插件的配置項能夠不填。
而後使用npm install gitbook-plugin-page-treeview命令安裝插件。
使用效果以下圖:
clipboard.png
目錄線面一行版權的信息，若是想要刪除，須要在插件目錄中打開：/node_modules/gitbook-plugin-page-treeview/lib/index.js。
大約43行，在generateContent方法定義中，該方法的返回值

return renderContent ? `<div class="treeview__container">${copyRight + renderContent}</div>` : '';
// 改爲：
return renderContent;

而後重啓服務或從新打包。

注意：
一、此方法適用於3.0.1版本的，其餘版本若是沒有請搜索renderContent,options.copyright,>Treeview<嘗試。
二、若是你從新安裝了這個插件，那麼就須要重新修改插件文件。

2.4.2 懸浮按鈕目錄

anchor-navigation-ex

{
    "plugins" : [ 
        "anchor-navigation-ex"
    ],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "showLevel": false, //標題是否顯示層級序號.頁面標題和導航中的標題都會加上層級顯示。
            "showGoTop": false // 是否顯示返回頂部按鈕
        },
    }
}

npm install gitbook-plugin-anchor-navigation-ex
anchor-navigation-ex頁面右上角生成一個灰色的按鈕，鼠標移入後會顯示灰色的目錄。

更多配置介紹：https://github.com/zq99299/gi...

下面的插件也能生成懸浮頁內目錄，可是頁面只有二級、三級、標題是不會顯示，這裏僅供參考
page-toc-button、ancre-navigation

{
    "plugins" : [ 
        "page-toc-button",
        "ancre-navigation"
    ],
    "pluginsConfig": {
        "page-toc-button": {
            "maxTocDepth": 2,  // 標題的最大深度（2 = h1 + h2 + h3）。不支持值> 2。
            "minTocSize": 2    // 顯示toc按鈕的最小toc條目數。
           }
    }
}

安裝：

npm install gitbook-plugin-page-toc-button
npm install gitbook-plugin-ancre-navigation

page-toc-button插件在頁面右上角生成一個黑色的按鈕，鼠標移入後會顯示黑色的目錄。
ancre-navigation插件頁面右上角生成一個白色的按鈕，頁面右下角生成一個返回頂部的按鈕。

2.5 回到頂部按鈕

在book.json的plugins參數中添加插件名和配置信息：

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

使用npm install gitbook-plugin-back-to-top-button命令安裝插件。

3. 其餘插件

3.1 摺疊模塊(頁面內容可摺疊)

3.1.1 accordion

這個插件名叫手風琴，能夠實現將內容隱藏起來，外部顯示模塊標題和顯示箭頭，點擊箭頭可顯示裏面的內容。

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

{
    "plugins": ["accordion"]
}

而後使用npm install gitbook-plugin-accordion命令安裝插件。
md文件的寫法：

%accordion%模塊標題%accordion%
內容部分
%/accordion%

使用效果(https://artalar.github.io/git...：
clipboard.png

3.1.2 sectionx

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

{
    "plugins": ["sectionx"],
    "pluginsConfig": {
        "sectionx": {
          "tag": "b"       // 設置標題的標籤，可選值：h1, h2, h3, h4, h5, h6, b
        }
     }
}

標籤的 tag 最好是使用 b 標籤，若是使用 h1-h6 可能會和其餘插件衝突。

而後使用npm install gitbook-plugin-sectionx命令安裝插件。

在MD文件中的用法：

<!--sec data-title="這裏寫標題" data-id="section0" data-show=true ces-->
這裏是內容   
dsadsa    
dadsa
<!--endsec-->

最終效果：
clipboard.png
在線例子：https://ymcatar.gitbooks.io/g...

其中參數的做用：

data-title：收縮模塊的標題，大小在插件參數配置裏面配置，注意：HTML中實體字符要轉義
data-id：收縮模塊的id，用於插件的控制按鈕，下面講解
data-show：模式默認是收縮仍是展開的，true：展開，false：隱藏

sectionx還能夠設置按鈕來顯示或隱藏代碼摺疊模塊，md寫法以下：

<button class="section" target="showCode" show="顯示文案" hide="隱藏文案"></button>
<!--sec data-title="這裏寫標題" data-id="showCode" data-show=true ces-->
這裏是內容   
dsadsa     
dadsa
<!--endsec-->

效果以下圖：

clipboard.png
其中參數的做用：

class：類名必須是 section
target：須要影藏的模塊名，名字與 data-id一致
show：模塊隱藏時，按鈕顯示的文案
hide：模塊顯示時，按鈕顯示的文案

3.2 右上角添加github圖標

在book.json的plugins參數中添加插件名和配置信息：

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

而後使用npm install gitbook-plugin-github命令安裝插件。
注意：
若是使用npm命令安裝後報錯GitBook doesn't satisfy the requirements of this plugin: >=4.0.0-alpha.0.
請使用gitbook install來安裝.
或者npm uninstall gitbook-plugin-github卸載後，使用npm i gitbook-plugin-github@2.0.0安裝，而後查看是否還報錯。

3.3 edit-link在線編輯文件

book.json中插件名和配置信息：

{
    "plugins": ["edit-link"],
    "pluginsConfig": {
      "edit-link": {
            "base": "//github.com/yulilong/book/edit/master",
            "label": "編輯此頁面"
       }
    }
}

使用npm i gitbook-plugin-edit-link命令安裝插件。
下過以下圖：

clipboard.png
點擊編輯按鈕，便可跳轉到github倉庫在線編輯這個文件。

3.4 修改網站的favicon.ico

github地址：https://github.com/menduo/git...
book.json中插件名和配置信息：

{
    "plugins": ["favicon"],
    "pluginsConfig": {
      "favicon": {
            "shortcut": "asset/img/favicon.ico",
            "bookmark": "asset/img/favicon.ico",
            "appleTouch": "asset/img/favicon.ico",
            "appleTouchMore": {
                "120x120": "asset/img/favicon.ico",
                "180x180": "asset/img/favicon.ico"
            }
        }
    }
}

使用npm install gitbook-plugin-favicon命令安裝插件。
下過以下圖：

clipboard.png

注意：
一、圖標的格式必定要是.ico的，直接修改圖片的後綴爲.ico是無效的。
二、圖標的分辨率要是32*32的。
三、可在線把圖片轉成圖標：http://www.bitbug.net/

3.5 查看圖片

3.5.1 popup打開新的頁面查看圖片

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

{
    "plugins": [
        "popup"
    ],
}

使用npm install gitbook-plugin-popup命令安裝插件。

3.5.2 lightbox頁面彈窗顯示圖片

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

{
    "plugins": [
        "lightbox"
    ],
}

使用npm install gitbook-plugin-lightbox命令安裝插件。

3.6 prism代碼塊顏色插件

插件地址：https://github.com/gaearon/gi...
此插件須要禁用gitbook自帶的highlight插件。
book.json中插件名和配置信息：

{
    "plugins": ["prism", "-highlight"],
    "pluginsConfig": {
      "prism": {
        "css": [
          "prismjs/themes/prism-okaidia.css"
        ]
      }
    }
}

使用npm install gitbook-plugin-prism命令安裝插件。
效果以下圖：
clipboard.png

更多的顏色參考：https://github.com/gaearon/gi...

3.7 Gitalk評論插件

Gitalk插件的使用教程:https://segmentfault.com/a/11...

這個插件是須要在MD文件中寫入代碼的，在須要評論插件的MD文件的最下面寫入以下代碼：

<link rel="stylesheet" href="//cdn.bootcss.com/gitalk/1.5.0/gitalk.min.css">
<script src="//cdn.bootcss.com/gitalk/1.5.0/gitalk.min.js"></script>
<div id="gitalk-container"></div>
<script>
    var gitalk = new Gitalk({
    clientID: '2eb19afceda708b27e64', // GitHub Application Client ID
    clientSecret: '36aedb5a30321626a8631689fee5fafd5929f612', // GitHub Application Client Secret
    repo: 'book',              // 存放評論的倉庫
    owner: 'user',          // 倉庫的建立者，
    admin: ['user'],        // 若是倉庫有多我的能夠操做，那麼在這裏以數組形式寫出
    id: location.pathname,      // 用於標記評論是哪一個頁面的，確保惟一，而且長度小於50
    });
    gitalk.render('gitalk-container');    // 渲染Gitalk評論組件
 </script>

效果以下圖：
clipboard.png

3.8 hide-element隱藏元素

能夠隱藏不想看到的元素，好比導航欄中Published by GitBook。
hide-element是經過HTML元素的class名字來查找要隱藏的元素，想要隱藏元素找到元素的樣式類名加到插件配置裏面就能夠隱藏元素了。

在book.json的plugins參數中添加插件名和配置信息：

{
    "plugins": [
        "hide-element"
    ],
    "pluginsConfig": {
        "hide-element": {
            "elements": [".gitbook-link"]
        }
    }
}

而後使用npm install gitbook-plugin-hide-element命令安裝插件。

上面的配置信息中設置了隱藏的類名，因此Published by GitBook就看不見，效果以下圖：

clipboard.png

3.9 網站主題

3.9.1 theme-fexa

插件地址：https://github.com/tonyyls/gi...

book.json中插件名和配置信息：

{
    "plugins": [
        "theme-fexa"
    ],
    "variables": {
        "themeFexa":{
            "nav":[
                {
                    "url":"http://...",
                    "target":"_blank",
                    "name": "簡易教程"
                }
            ]
        },
    },
    "pluginsConfig": {
        "theme-fexa":{
            "search-placeholder":"輸入關鍵字搜索", //搜索框提示信息
            "logo":"./logo.png", //logo地址
            "favicon": "./favicon.ico" //ico地址
        }
    }
}

使用npm install gitbook-plugin-theme-fexa命令安裝插件。

效果以下圖：

clipboard.png

3.10 添加頁面顯示最後更新時間

在book.json的plugins參數中添加插件名和配置信息：

{
    "plugins": [
        "tbfed-pagefooter"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"",
            "modify_label": "該文件最後修改時間：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
    }
}

而後使用npm install gitbook-plugin-tbfed-pagefooter命令安裝插件。
頁面效果：

clipboard.png

參考資料

gitbook 實用插件
http://gitbook.zhangjikai.com...
https://blog.csdn.net/weixin_...

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程