Gitbook的插件配置

npm为Gitbook提供了很多插件，只需要在Gitbook项目配置npm项目，就可以下载相关插件使用。

[!NOTE] 插件应该在项目目录下安装，也就是说在当前项目文件下安装，才会出现在package.json文件中。

1. 搜索插件

插件gitbook-plugin-search-pro支持中文搜索，详情参考官方文档，首先在项目中安装该插件

npm i gitbook-plugin-search-pro

然后在book.js文件中添加配置项

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

该插件能够搜索到全文匹配字符，搜索能力非常强。

2. 代码插件

插件gitbook-plugin-code用于排版代码，详情参考官方文档，首先在项目中安装该插件

npm i gitbook-plugin-code

然后在book.js文件中添加配置项

"plugins" : [ "code" ],
"pluginsConfig": {
  "code": {
    "copyButtons": false
  }
}

3. 主题插件

gitbook-plugin-theme-

4. 隐藏Gitbook默认设置

Gitbook页面有诸如“Published with GitBook”的默认设置，可用插件gitbook-plugin-hide-element使之隐藏。 插件gitbook-plugin-hide-element的官方文档，首先在项目中安装该插件

npm i gitbook-plugin-hide-element

然后在book.js文件中添加配置项

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

完成上述配置，就可以将“Published with GitBook”的默认设置去掉。

5. 添加提示、警告等提示框

插件gitbook-plugin-flexible-alerts用于添加提示、警告等提示框，参考官方文档，首先在项目中安装该插件

npm i gitbook-plugin-flexible-alerts

然后在book.js文件中添加配置项，以下是其中一种配置方式，更多配置参数，可查看官方文档。

{
  "plugins": [
    "flexible-alerts"
  ],
  "pluginsConfig": {
    "flexible-alerts": {
      "style": "flat"
    }
  }
}

例如给出具体的样式配置

"flexible-alerts": {
  // "style": "flat",
  "note": {"label" : "注意"},
  "tip": {"label" : "提示"},
  "warning": { "label": "warning" },
  "danger": { "label": "危险" }
}

使用方式如下，> [!NOTE]给出“提示”，后面跟着相关文本；其他提示框也类似，例如下面的“TIPs”。

> [!NOTE]
> 文本

[!NOTE] An alert of type 'tip' using alert specific style 'flat' which overrides global style 'callout'. In addition, this alert uses an own heading and hides specific icon.

> [!TIP]
> An alert of type 'tip' using alert specific style 'flat' which overrides global style 'callout'.
> In addition, this alert uses an own heading and hides specific icon.

[!TIP] An alert of type 'tip' using alert specific style 'flat' which overrides global style 'callout'. In addition, this alert uses an own heading and hides specific icon.

更多高级用法，参考官方文档。

6. 菜单折叠

插件gitbook-plugin-expandable-chapters用于折叠菜单，参考官方文档，首先在项目中安装该插件。

npm i gitbook-plugin-expandable-chapters

然后在book.js文件中添加配置项

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

7. 返回顶部

插件gitbook-plugin-back-to-top-button用于设置返回顶部按钮，参考官方文档，首先在项目中安装该插件。

npm i gitbook-plugin-back-to-top-button

然后在book.js文件中添加配置项，以下是其中一种配置方式，更多配置参数，可查看官方文档。

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

设置返回顶部按钮之后，可能受到原来默认的左右导航箭头影响，不能正常显示返回顶部的按钮，需要去掉左右导航箭头，去除左右导航箭头可以配置CSS样式（CSS样式设置参考样式调整）。

/* 隐藏导航箭头 */
.navigation-next, .navigation-prev {
    display: none !important;
}
/* 或者更具体的选择器 */
button[data-testid="next-chapter-button"],
button[data-testid="previous-chapter-button"] {
    display: none !important;
}

8. 页内导航

插件gitbook-plugin-page-toc用于页内导航，参考官方文档，首先在项目中安装该插件。

npm i gitbook-plugin-page-toc

然后在book.js文件中添加配置项，以下是其中一种配置方式，更多配置参数，可查看官方文档。

{
  "plugins": [ "page-toc" ],
  "pluginsConfig": {
    "page-toc": {
      "selector": ".markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4",
      "position": "before-first",
      "showByDefault": true
    }
  }
}

默认情况下显示导航目录，如果showToc设置为false，则会隐藏导航目录，但是显示不了打开导航的按钮。可以设置showToc为false，在需要打开导航目录的markdown文档顶部添加以下代码，则该页面出现导航目录。

---
showToc: true
---

如果是某个页面不需要导航目录，则设置showToc为false

---
showToc: false
---

页面上可能会有一些元素遮挡导航目录，这时候可以通过下面的方式将导航目录浮动到页面顶层。

/* 重置所有可能的高 z-index 元素 */
.book .book-header,
.book .book-summary,
.book .book-body .navigation,
.markdown-section .code-toolbar {
    z-index: 100 !important;
}

/* 模态框和弹出层 */
.modal, .popup, .tooltip {
    z-index: 1000 !important;
}

/* 页面目录 - 最高优先级 */
.page-toc {
    z-index: 2147483647 !important; /* 接近最大整数值 */
    position: fixed !important;
    right: 20px !important;
    top: 80px !important;

    /* 创建新的层叠上下文 */
    transform: translate3d(0, 0, 0);
    isolation: isolate;
}

/* 确保在移动端也能正常显示 */
@media (max-width: 1240px) {
    .page-toc {
        z-index: 2147483647 !important;
        position: fixed !important;
        top: 60px !important;
        right: 10px !important;
        width: 250px !important;
    }
}

这个插件的另一个缺点是，当页面出现导航目录的时候，会导致顶部间距增加，或许可以在website.css中设置相应的样式调整。

9. 页内导航与返回顶部

插件gitbook-plugin-anchor-navigation-ex用于页内导航和返回顶部，参考官方文档，首先在项目中安装该插件。

npm i gitbook-plugin-anchor-navigation-ex

然后在book.js文件中添加配置项

{
  "plugins": [
       "anchor-navigation-ex"
  ]
}

该插件解决了插件gitbook-plugin-page-toc的问题，合并了插件gitbook-plugin-back-to-top-button和插件gitbook-plugin-page-toc的功能。该插件更详细的配置如下

"anchor-navigation-ex":{
  "showLevel": true,
  "associatedWithSummary": true,
  "printLog": false,
  "multipleH1": true,
  "mode": "pageTop", // pageTop or float
  "showGoTop":true,
  "float": {//悬浮在右上角
      "floatIcon": "fa fa-navicon",
      "showLevelIcon": false,
      "level1Icon": "fa fa-hand-o-right",
      "level2Icon": "fa fa-hand-o-right",
      "level3Icon": "fa fa-hand-o-right"
  },
  "pageTop": {//页面底部插入
      "showLevelIcon": false,
      "level1Icon": "fa fa-hand-o-right",
      "level2Icon": "fa fa-hand-o-right",
      "level3Icon": "fa fa-hand-o-right"
  }
}

插件gitbook-plugin-page-toc的返回顶部按钮固定不变，有些呆板，可以设置参数showGoTop为false，然后用插件gitbook-plugin-back-to-top-button设置返回顶部按钮。

10. TeX 公式

插件gitbook-plugin-katex用于处理 TEX 公式，参考官方文档，首先在项目中安装该插件。

npm i gitbook-plugin-katex

然后在book.js文件中添加配置项，以下是其中一种配置方式，更多配置参数，可查看官方文档。

{
    "plugins": ["katex"]
}

例如，下面的代码，放在两个 $$ 之间，与latex的语法格式相同，编译之后就是latex公式。

Inline math: {% math %}\int_{-\infty}^\infty g(x) dx{% endmath %}

Block math:
{% math %}
\int_{-\infty}^\infty g(x) dx
{% endmath %}

Inline math: $\int_{-\infty}^\infty g(x) dx$

Block math: $\int_{-\infty}^\infty g(x) dx$

$$ 在gitbook中有特殊含义，表示数学公式的开始，要打印 $$，可以用转义的方式，如 \$\$。

11. 代码高亮

插件npm i gitbook-plugin-prism用于处理代码高亮，参考官方文档，首先在项目中安装该插件。

npm i gitbook-plugin-prism

然后在book.js文件中添加配置项，以下是其中一种配置方式，更多配置参数，可查看官方文档。

{
  "plugins": ["prism", "-highlight"]
}

"pluginsConfig": {
    "prism": {
      "css": ["prismjs/themes/prism-solarizedlight.css"],
      "lang": {"flow": "typescript"},
      "ignore": ["mermaid","eval-js"]
    },
}

在使用的时候，需要指定编程语言，例如上面采用的是json。