插件安装及常用插件

1. 插件安装

可以在npm上搜索想要的gitbook插件，有以下两种安装方法。

（1）使用gitbook install

在book.json添加插件名称，插件名称前加-，表示移除插件，如：

"plugins" : [ 
        "page-toc-button",
        "splitter",
        "code",
        "-lunr", 
        "-search", 
        "search-pro",
        "-sharing", 
        "sharing-plus",
        "pageview-count",
        "auto-scroll-table",
        "popup",  
        "custom-favicon",
        "anchors",
        "klipse",
        "-highlight",
        "prism"
    ],

接下来在终端运行gitbook install。

$ gitbook install
info: installing 11 plugins using npm@3.9.2
info:
info: installing plugin "page-toc-button"
info: install plugin "page-toc-button" (*) from NPM with version 0.1.1
info: >> plugin "page-toc-button" installed with success
...

（2）用npm安装

npm install gitbook-plugin-X

# Example
$ npm install gitbook-plugin-flexible-alerts
npm WARN saveError ENOENT: no such file or directory, open 'D:\docs\gitbook\gitbook-notes\package.json'
npm WARN enoent ENOENT: no such file or directory, open 'D:\docs\gitbook\gitbook-notes\package.json'
npm WARN gitbook-notes No description
npm WARN gitbook-notes No repository field.
npm WARN gitbook-notes No README data
npm WARN gitbook-notes No license field.

+ gitbook-plugin-flexible-alerts@1.0.3
added 1 package from 1 contributor, removed 14 packages and audited 84 packages in 2.901s

1 package is looking for funding
  run `npm fund` for details

found 23 vulnerabilities (2 low, 13 moderate, 6 high, 2 critical)
  run `npm audit fix` to fix them, or `npm audit` for details

（3）一点心得

使用方法一，会重新安装插件，那么之前对插件的修改就覆盖掉了。安装新插件，建议还是使用方法二。

但奇怪的是，使用npm install gitbook-plugin-X会删除一些已经安装的插件，进而导致如下错误：

$ gitbook build
info: 23 plugins are installed
info: 20 explicitly listed

Error: Couldn't locate plugins "page-treeview, back-to-top-button, scroll-to-top, insert-logo", Run 'gitbook install' to install plugins from registry.

要不，还是使用方法一，在安装的时候，把plugins内容先拷到记事本，只留下要装的插件名称，装完再拷回去。

2. 一些常用插件

2.1 目录

（1）页内目录

在页面内生成目录，使用gitbook-plugin-page-treeview。

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

但会在目录下方产生这么一段文字：

TreeviewCopyright © Spark & Shine all right reserved, powered by aleen42

去掉这段文字。打开node_modules/gitbook-plugin-page-treeview/lib/index.js，找到这一行，删掉copyRight +。

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

但还有一个小问题，就是目录跟正文间距太大了，解决方法：修改.treeview__container的样式，打开gitbook-plugin-page-treeview/assets/style.css文件，将.treeview__container中的margin-bottom设小。

.treeview__container {
    position: relative;
    margin-bottom: 5px;
    padding-bottom: 10px;
}

也可以将上述css放到styles/website.css文件，再设置book.json，省得插件更新时需要重新修改：

"pluginsConfig": {
        "styles": {
            "website": "styles/website.css"
        }
}

最后效果如下：

gitbook-plugin-page-treeview-example

（2）悬浮目录

文章如果很长，悬浮目录就很有必要了。悬浮目录使用插件gitbook-plugin-page-toc-button。

{
    "plugins" : [ 
        "page-toc-button" 
    ],
    "pluginsConfig": {
        "page-toc-button": {
            "maxTocDepth": 2,
            "minTocSize": 2
           }
    }
}

（3）回到顶部

对于长文，回到顶部功能就很有必要了，使用插件gitbook-plugin-back-to-top-button，

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

2.2 左侧边栏

（1）左侧目录折叠

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

在寻找一款，默认是全部展开的插件。

（2）支持中文搜索

去除默认插件-lunr（为search插件提供后端）和-search，使用gitbook-plugin-search-pro。

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

2.3 正文

（1）在页脚放版权信息

使用插件gitbook-plugin-tbfed-pagefooter，copyright和modify_label支持html标签。

{
    "plugins": [
       "tbfed-pagefooter"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"本文系Spark & Shine原创，转载需注明出处",
            "modify_label": "最近一修改时间：",
            "modify_format": "YYYY-MM-DD HH:mm"
        }
    }
}

去除all right reserved, powered by Gitbook，修改node_modules/gitbook-plugin-tbfed-pagefooter/index.js文件，

//_copy = _c ? _c + ' all right reserved，' + _copy : _copy;
_copy = _c;

最后，得到如下效果：gitbook-plugin-tbfed-pagefooter-example

一个问题，如何得到文章的创建时间？每次编译书籍产生新的html文件，创建时间都是当下的。

2.4 代码

（1）显示代码行号和复制按钮

使用插件gitbook-plugin-code。

"plugins" : [ 
        "code",
        ...
],

如果不需要复制代码按钮，进行如下配置：

"pluginsConfig": {
  "code": {
    "copyButtons": false
  }
}

（2）代码高亮

Prism是一个轻量级、可扩展的代码高亮插件。Prism适用于GitBook的插件是gitbook-plugin-prism，代码主题在node_modules/prismjs/themes/目录下挑，进行如下设置。

"pluginsConfig": {
        "prism": {
          "css": [
          "prismjs/themes/prism-tomorrow.css"
        ]
        }
}

（3）交互式代码

使用插件gitbook-plugin-klipse ，在语言前加上eval- (evaluate)。

```eval-python
print [x + 1 for x in range(10)]
```

2.5 显示/隐藏内容

使用插件gitbook-plugin-accordion，在book.json中添加，

{
  "plugins": ["accordion"]
}

使用方法如下：

%accordion%Some title here%accordion%

Any content here

%/accordion%

2.6 其他

我目前使用的插件如下：

"plugins" : [ 
        "page-toc-button",
        "page-treeview",
        "back-to-top-button",
        "splitter",
        "code",
        "-lunr", 
        "-search", 
        "search-pro",
        "-sharing", 
        "-sharing-plus",
        "pageview-count",
        "auto-scroll-table",
        "popup",  
        "custom-favicon",
        "scroll-to-top",
        "anchors",
        "klipse",
        "-highlight",
        "prism",
        "insert-logo",
        "tbfed-pagefooter"
],

3. 安装MathJax

在book.json插件中添加了mathjax-pro，运行gitbook install，提示错误if (args[ii] == null) throw missingRequiredArg(ii) Error: Missing required argument #1，如下：

info: install plugin "mathjax-pro" (*) from NPM with version 1.1.2
C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\node_modules\aproba\index.js:25
    if (args[ii] == null) throw missingRequiredArg(ii)
                          ^

Error: Missing required argument #1
    at andLogAndFinish (C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\lib\fetch-package-metadata.js:31:3)
    at fetchPackageMetadata (C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\lib\fetch-package-metadata.js:51:22)
    at resolveWithNewModule (C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\lib\install\deps.js:490:12)
    at C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\lib\install\deps.js:491:7
    at C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\node_modules\iferr\index.js:13:50
    at C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\lib\fetch-package-metadata.js:37:12
    at addRequestedAndFinish (C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\lib\fetch-package-metadata.js:67:5)
    at returnAndAddMetadata (C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\lib\fetch-package-metadata.js:121:7)
    at pickVersionFromRegistryDocument (C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\lib\fetch-package-metadata.js:138:20)
    at C:\Users\SU\.gitbook\versions\3.2.3\node_modules\npm\node_modules\iferr\index.js:13:50 {
  code: 'EMISSINGARG'
}

解决方法，先运行npm i gitbook-plugin-mathjax-pro，再运行gitbook install，终于搞定了:-)

info: installing plugin "mathjax-pro"
info: install plugin "mathjax-pro" (*) from NPM with version 0.0.6
info: >> plugin "mathjax-pro" installed with success
本文系Spark & Shine原创，转载需注明出处本文最近一次修改时间 2023-03-22 23:01

results matching ""

    No results matching ""