# 插件

## GitBook插件

### 为什么用插件

> Gitbook插件可以解决一些网站不太方便的地方，如侧边栏导航不能收缩，自带搜索不支持中文等。

### 插件安装

* `gitbook install`： 安装 `book.json` 文件 `plugins` 属性中指定的插件。
* `npm` 命令安装：`npm init` 初始化 `package.json` 文件，然后通过 `npm install gitbook-plugin-插件名` 命令来快速安装依赖的插件。

> 插件的说明文档中，一般都建议使用 `gitbook install` 的方式安装插件，**但是这种方式下载比较慢而且是全部插件都安装一遍**，如果只安装一个插件的话**建议使用 `npm` 命令方式安装**。

**注意**：插件一定要在 `book.json`文件的 `plugins`中**先添加才能生效**，如果只是安装了插件，而没配置的话是不会生效的。

#### `npm`命令安装

`npm init` 后如下（可以发现之前通过 `gitbook install` 方式安装的插件也在依赖之中）：

```javascript
{
  "name": "gitook",
  "version": "1.0.0",
  "description": "....",
  "main": "index.js",
  "dependencies": {
    "gitbook-plugin-anchor-navigation-ex-toc": "^0.0.11",
    "gitbook-plugin-copy-code-button": "^0.0.2",
    "gitbook-plugin-tbfed-pagefooter": "^0.0.1",
    "gitbook-plugin-anchors": "^0.7.1",
    "gitbook-plugin-search-plus": "^1.0.3"
  },
  "devDependencies": {},
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/leoXuLei/gitBookNotes.git"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/leoXuLei/gitBookNotes/issues"
  },
  "homepage": "https://github.com/leoXuLei/gitBookNotes#readme"
}
```

示例：安装 `splitter` 插件如下，同时也会更新 `package.json` 文件中的依赖。

```javascript
$ npm i gitbook-plugin-splitter
npm notice created a lockfile as package-lock.json. You should commit this file.

+ gitbook-plugin-splitter@0.0.8
added 1 package from 1 contributor in 4.181s
```

### 插件配置

在 `book.json` 的 `pluginsConfig` 中对插件功能进行配置，本书配置文件见 [本书籍配置文件](https://github.com/leoXuLei/gitBookNotes/tree/145fa57cd5096200cde04cfda23f8441b528c41e/expand/configuration.html#%E6%9C%AC%E4%B9%A6%E7%9A%84%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6)

### 默认插件

GitBook 默认带有7个插件（功能性5个，搜索有2个，主题1个）：

```javascript
highlight： // 语法高亮
search： // 导航栏查询功能（不支持中文）
sharing：// 右上角分享功能
font-settings：// 字体设置（最上方的"A"符号）
livereload：// 为GitBook实时重新加载 
lunr: // lunr 搜索插件后台服务
theme-default: // 主题
```

如果要去除自带的插件，可以在插件名称前面加 -，如下：

```javascript
"plugins": [
    "-sharing",
    "-lunr",
    "-search", 
]
```

## 常用插件

下面记录一些实用的插件，如果要指定插件的版本可以使用 `plugin@0.3.1`。下面的插件在 GitBook 的 3.2.2 版本中可以正常工作，因为一些插件可能不会随着 GitBook 版本的升级而升级，即下面的插件可能不适用高版本的 GitBook，所以这里指定了 GitBook 的版本。这里只是列举了一部分插件，如果有其它的需求，可以到 [插件官网](https://plugins.gitbook.com/) 搜索相关插件。

* [anchors - 添加 Github 风格的锚点](#anchors)
* [anchor-navigation-ex - 添加Toc到侧边悬浮导航以及回到顶部按钮](#anchor-navigation-ex)
* [code - 代码块复制](#code)
* [copy-code-button - 代码块复制](#copy-code-button)
* [donate - 打赏插件](#donate)
* [edit-link - 链接到当前页源文件上](#edit-link)
* [expandable-chapters-small - 使左侧的章节目录可以折叠](#expandable-chapters-small)
* [github - 添加github图标](#github)
* [github Buttons - 添加项目在 Github 上的 star、fork、watch 信息](#github-buttons)
* [lightbox - 图片点击弹窗显示](#lightbox)
* [popup - 打开新的页面查看图片](#popup)
* [prism - 代码块颜色插件](#prism)
* [search -plus - 支持中文搜索](#search-plus)
* [sharing - 分享当前页面](#sharing)
* [splitter - 使侧边栏的宽度可以自由调节](#splitter)
* [tbfed-pagefooter - 为页面添加页脚](#tbfed-pagefooter)
* [versions-select - 多个版本选择](#versions-select)

### anchors

添加 Github 风格的锚点样式（标题不能有大写字母，可以有`-`）

```javascript
使用格式：
    [说明文字](#标题)
    ## 标题

实例：
    [search -plus](#search-plus)
    ## search -plus
```

```javascript
{
    "plugins" : [ "anchors" ]
}
```

### anchor-navigation-ex

添加Toc到侧边悬浮导航以及回到顶部按钮。需要注意以下两点：

* 本插件只会提取 h\[1-3] 标签作为悬浮导航
* 只有按照以下顺序嵌套才会被提取

  ```javascript
  # h1
  ## h2
  ### h3
  必须要以 h1 开始，直接写 h2 不会被提取
  ## h2
  ```

[中文版说明](https://github.com/zq99299/gitbook-plugin-anchor-navigation-ex) [详细配置说明](https://github.com/zq99299/gitbook-plugin-anchor-navigation-ex/blob/master/doc/config.md)

```javascript
{
    "plugins": ["anchor-navigation-ex"],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "showLevel": true,  // 标题是否显示层级序号，页面标题和导航中的标题都会加上层级显示。
            "associatedWithSummary": true, // 页面内的序号是否与 summary.md 中官方默认主题生成的序号相关联。
            "printLog": false,  // 是否显示日志
            "multipleH1": false, // 是否有多个H1标题
            "isRewritePageTitle": true,
            "isShowTocTitleIcon": true,
            "mode": "float",
            "showGoTop":true,
            "tocLevel1Icon": "fa fa-hand-o-right",
            "tocLevel2Icon": "fa fa-hand-o-right",
            "tocLevel3Icon": "fa fa-hand-o-right"
            "float": {
              "floatIcon": "fa fa-navicon", // // 配置导航图标，如果你喜欢原先的 锚 图标可以配置为 fa-anchor
              "showLevelIcon": false, // 是否显示层级图标
                "level1Icon": "fa fa-hand-o-right", //层级的图标css
                "level2Icon": "fa fa-hand-o-right",
                "level3Icon": "fa fa-hand-o-right"
            },
            "pageTop": {
                "showLevelIcon": false,
                "level1Icon": "fa fa-navicon",
                "level2Icon": "fa fa-hand-o-right",
                "level3Icon": "fa fa-hand-o-right"
            }
        }
    }
}
```

### code

为代码块添加复制的图标。跟 `copy-code-button` 插件相比较：添加了代码的行号，右上角还多了一个复制的图标，点击复制后图标变成对号。

```javascript
{
    "plugins": ["code"]
    "pluginsConfig": {
        "code": {
            "copyButtons": true
        }
    }
}
```

### copy-code-button

为代码块添加复制的按钮。图标显得有点突兀，可能和当前主题不搭。还有就是点击 Copy 以后，会全选当前的代码，有点奇怪。

```javascript
{
    "plugins": ["copy-code-button"]
}
```

### donate

打赏插件

```javascript
{
    "plugins": ["donate"],
    "pluginsConfig": {
        "donate": {
            "wechat": "https://xxxx.weixin.png",
            "alipay": "https://xxx.alipay.png",
            "title": "",
            "button": "赏",
            "alipayText": "支付宝打赏",
            "wechatText": "微信打赏"
        }
    }
}
```

### edit-link

如果将 GitBook 的源文件保存到github或者其他的仓库上，使用该插件可以链接到当前页的源文件上。

```javascript
{
    "plugins": ["edit-link"],
    "pluginsConfig": {
        "edit-link": {
            "base": "https://github.com/USER/REPO/edit/BRANCH",
            "label": "Edit This Page"
        }
    }
}
```

### expandable-chapters-small

使左侧的章节目录可以折叠

```javascript
{
    "plugins": ["expandable-chapters-small"]
}
```

### github

右上角添加github图标，点击图标跳转到对应的Github地址。

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

注意： 如果使用 `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`安装，然后查看是否还报错。

### github-buttons

添加项目在 github 上的 star、watch、fork情况

```javascript
"size": "small" || "large"
"width": number
"height": number
```

```javascript
{
    "plugins": ["github-buttons"],
    "pluginsConfig": {
        "github-buttons": {
            "buttons": [{
                "user": "leoXuLei",
                "repo": "gitBookNotes",
                "type": "star",
                "size": "small",
                "width": "100",
            }, {
                "user": "leoXuLei",
                "type": "follow",
                "width": "100",
                "count": false,
                "size": "small"
            }]
        }
    }
}
```

效果如下： ![gitBookPluginGithubButtonsPreview](https://1600428340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MCatL6ay8oxlAjHmAmo%2Fsync%2F5859e946ca29be1e8fadb1febf776b8672bf733c.png?generation=1596341976867570\&alt=media)

### lightbox

点击图片弹窗显示

```javascript
{
    "plugins": ["lightbox"]
}
```

### popup

点击图片打开新的页面查看图片

```javascript
{
    "plugins": ["popup"]
}
```

### prism

代码块颜色插件，[插件地址](https://github.com/gaearon/gitbook-plugin-prism)

```javascript
{
  "plugins": ["prism", "-highlight"],
  "pluginsConfig": {
      "prism": {
        "css": [
          "prismjs/themes/prism-okaidia.css"
        ]
      }
    }
//   syntax-highlighting/assets/css/prism/prism-xonokai.css
}
```

* 默认代码块风格（**未加JS标识**）：

  ![gitBookCodeStylePreview](https://1600428340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MCatL6ay8oxlAjHmAmo%2Fsync%2F54b17448e2126cb12a9bb6beed736d7f91c87b91.png?generation=1596341975883523\&alt=media)
* 默认代码块风格（**加了JS标识**）：

  ![gitBookCodeStyleJSPreview](https://1600428340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MCatL6ay8oxlAjHmAmo%2Fsync%2F5285f01fde45e5baf445fd1c08a86196a3c23d34.png?generation=1596341978853457\&alt=media)
* 使用 `prism` 代码块风格 `prism-okaidia.css` （**未加JS标识**）：

  ![gitBookPluginPrismPreview1](https://1600428340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MCatL6ay8oxlAjHmAmo%2Fsync%2Fc7c54777741886e67d7f69fef9f745c78d5ec64b.png?generation=1596341977837349\&alt=media)
* 使用 `prism` 代码块风格 `prism-okaidia.css` （**加JS标识**）：

  ![gitBookPluginPrismPreview2](https://1600428340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MCatL6ay8oxlAjHmAmo%2Fsync%2F0dc5233d61e02f30c447faac7630adb755ec4905.png?generation=1596341979969471\&alt=media)

### search -plus

支持中文搜索，需要将默认的 `search` 和 `lunr` 插件去掉。

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

### sharing

分享当前页面，gitbook的默认插件，使用下面方式来禁用

```javascript
{
    "plugins": ["-sharing"]
}
```

配置：

```javascript
"pluginsConfig": {
    "sharing": {
        "weibo": true,
        "facebook": true,
        "twitter": true,
        "google": false,
        "instapaper": false,
        "vk": false,
        "all": [
            "facebook", "google", "twitter",
                "weibo", "instapaper"
        ]
    }
}
```

### splitter

使侧边栏的宽度可以自由调节

```javascript
{
    "plugins": ["splitter"]
}
```

### tbfed-pagefooter

为页面添加页脚

```javascript
{
    "plugins": [ "tbfed-pagefooter"],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"Copyright &copy zhangjikai.com 2017",
            "modify_label": "该文件修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}
```

### versions-select

添加版本选择的下拉菜单，针对文档有多个版本的情况

```javascript
{
    "plugins": [ "versions-select" ]
    "pluginsConfig":{
        "versions": {
            "options": [
                {
                    "value": "https://www.gitbook.com",
                    "text": "v1.0"
                },
                {
                    "value": "https://www.gitbook.com",
                    "text": "v2.0"
                }
            ]
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://leoxulei.gitbook.io/leospace/kuo-zhan/plugin.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.