GitBook（HonKit）插件篇

HonKit 完全兼容原版 GitBook 插件生态，插件是文档功能扩展的核心方式，可实现评论、搜索美化、目录折叠、版权保护、页面美化、数据统计等进阶能力。

插件分为两大类，遵循统一社区规范：

  • 功能插件：命名规范 gitbook-plugin-*，用于拓展文档交互、工具能力
  • 主题插件：命名规范 gitbook-theme-*，用于修改文档整体样式、布局风格

旧版官方插件市场 plugins.gitbook.com 已停止维护，目前所有插件统一从 NPM 搜索安装，完全适配 HonKit 构建体系。

插件安装流程

HonKit 与旧版 GitBook 插件安装逻辑不同，gitbook install 不再支持，必须通过 NPM 本地安装依赖。

步骤如下：

  • 安装插件依赖（项目本地安装，推荐）：npm install gitbook-plugin-xxx --save-dev；
  • 配置插件：在项目根目录 book.json 中声明插件与参数；
  • 生效构建：重新执行 honkit serve 或 honkit build 即可生效。

趣味增强插件（交互美化）

页面底部添加打赏按钮，点击弹出微信/支付宝二维码，适配个人博客、技术文档场景。

{
  "plugins": [
    "donate"
  ],
  "pluginsConfig": {
    "donate": {
      "wechat": "微信收款二维码URL",
      "alipay": "支付宝收款二维码URL",
      "title": "",
      "button": "赏",
      "alipayText": "支付宝打赏",
      "wechatText": "微信打赏"
    }
  }
}

disqus 评论插件

老牌静态页评论插件，可实现文档动态评论功能。

使用限制：国内无法直接访问 disqus.com，常规环境无法正常加载，仅作为海外部署方案备选，国内不推荐使用。

{
  "plugins": ["disqus"],
  "pluginsConfig": {
    "disqus": {
      "shortName": "你的disqus唯一标识"
    }
  }
}

gitalk 评论插件（国内首选）

替代 Disqus 的最优国内方案，基于 GitHub Issue 实现评论区，依托 GitHub 授权，稳定无墙、无需第三方服务器，适配所有托管在 GitHub 的文档项目。

申请 GitHub OAuth 授权

登录 GitHub 账号，前往 GitHub 开发者应用注册页面 新建应用：

  • Application name：自定义文档名称
  • Homepage URL：填写你的 HonKit 文档线上地址
  • Authorization callback URL：与首页 URL 保持一致

注册成功后，保存 Client ID、Client Secret（核心密钥，后续配置必需）。

页面集成配置

在页面 HTML 中引入样式、脚本并初始化（可全局注入实现所有页面生效）：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js"></script>
<div id="gitalk-container"></div>

<script>
var gitalk = new Gitalk({
    "clientID": "你的ClientID",
    "clientSecret": "你的ClientSecret",
    "repo": "仓库名称",
    "owner": "仓库所有者用户名",
    "admin": ["管理员用户名"],
    "id": location.pathname,      
    "distractionFreeMode": false  
});
gitalk.render("gitalk-container");
</script>

核心参数说明

  • clientID / clientSecret：必填，GitHub 应用密钥
  • repo / owner：必填，文档对应的 GitHub 仓库信息
  • admin：必填，仓库管理员，用于初始化 Issue 评论区
  • id：页面唯一标识，长度需小于50，避免报错
  • distractionFreeMode：可选，全屏遮罩效果，默认关闭

注意：本地预览无法生效，必须部署到线上域名；首次使用需管理员手动初始化评论 Issue。

mygitalk 简化评论插件

封装版 Gitalk 插件，无需手动嵌入 HTML 代码，直接通过 book.json 一键配置，开箱即用。

{
  "plugins" : ["mygitalk"],
  "pluginsConfig": {
    "mygitalk": {
        "clientID": "你的ClientID",
        "clientSecret": "你的ClientSecret",
        "repo": "仓库名称",
        "owner": "仓库所有者",
        "admin": ["管理员用户名"],
        "distractionFreeMode": false
    }
  }
}

change_girls 自动切换背景

自定义文档背景图，支持定时自动轮播，美化页面视觉效果。

{
    "plugins":["change_girls"],
    "pluginsConfig": {
        "change_girls" : {
            "time" : 10,
            "urls" : [
                "背景图URL1", 
                "背景图URL2"
            ]
        }
    }
}

防止文档恶意转载，复制内容时自动追加版权信息，页面底部展示来源、作者、站点信息。

{
    "plugins": ["copyright"],
    "pluginsConfig": {
        "copyright": {
        "site": "站点名称",
        "author": "作者名称",
        "website": "官网地址",
        "image": "版权图标URL"
        }
    }
}

readmore 公众号引流插件

对接 OpenWrite 平台，实现「关注公众号解锁全文」功能，适配博客流量引流场景。

{
    "plugins": ["readmore"],
    "pluginsConfig": {
        "readmore":{
            "blogId": "平台博客ID",
            "name": "公众号名称",
            "qrcode": "公众号二维码URL",
            "keyword": "解锁关键词"
        }
    }
}

advanced-emoji 表情支持

拓展 Markdown 语法，全量支持 Emoji 表情渲染，丰富文档内容展示。

{
    "plugins": [
        "advanced-emoji"
    ]
}

核心实用插件（优化阅读与体验）

search-plus 中文搜索增强

官方默认搜索插件不支持中文分词，search-plus 完美适配中文检索，搜索精准度大幅提升。

注意：必须禁用原生搜索插件，二者无法共存。

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

expandable-chapters-small 折叠导航

实现侧边栏多级目录折叠展开，箭头样式简约，适配长文档多章节场景。

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

summary 自动生成目录文件

自动扫描项目 Markdown 文件，一键生成/更新SUMMARY.md 目录文件，无需手动维护。

{
    "plugins": [
        "summary"
    ]
}

page-treeview 页内悬浮目录

在页面顶部生成文章层级目录，快速跳转段落，提升长文档阅读体验。

{
    "plugins": [
        "page-treeview"
    ],
    "pluginsConfig": {
        "page-treeview": {
            "copyright": "Copyright &#169; aleen42",
            "minHeaderCount": "2",
            "minHeaderDeep": "2"
        }
    }
}

自定义页面底部版权文案、文件修订时间，适配文档规范化展示。

{
    "plugins": ["tbfed-pagefooter"],
    "pluginsConfig": {
        "tbfed-pagefooter": {
          "copyright":"&copy; 你的用户名",
          "modify_label": "文件修订时间：",
          "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

pageview-count 阅读量统计

自动统计单页面访问次数，展示文档阅读数据。

{
  "plugins": [ "pageview-count"]
}

accordion 内容折叠模块

手风琴折叠效果，可隐藏冗余内容，点击展开查看详情，精简页面布局。

使用语法：在 Markdown 中通过专属标签包裹内容

%accordion%模块标题%accordion%
这里是折叠的正文内容
%/accordion%
{
  "plugins": ["accordion"]
}

hide-element 元素隐藏

隐藏页面多余元素（如默认的 GitBook 版权标识），精简页面。

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

splitter 侧边栏宽度调节

支持鼠标拖拽调整侧边目录栏宽度，适配不同屏幕阅读习惯。

{
    "plugins": [
        "splitter"
    ]
}

sharing-plus 增强分享

替换原生分享插件，新增微博、QQ、QZone 等国内主流分享渠道。

{
    "plugins": ["-sharing", "sharing-plus"],
    "pluginsConfig": {
        "sharing": {
             "douban": false,
             "facebook": false,
             "google": true,
             "pocket": false,
             "qq": false,
             "qzone": true,
             "twitter": false,
             "weibo": true,
          "all": [
               "douban", "facebook", "google", "instapaper", "linkedin","twitter", "weibo", 
               "messenger","qq", "qzone","viber","whatsapp"
           ]
       }
    }
}

klipse 在线代码运行

为代码块嵌入在线 IDE 能力，支持 JS、Python、PHP、Ruby 等多语言实时执行、预览结果。

{
    "plugins": ["klipse"]
}

github 仓库跳转

页面顶部展示 GitHub 图标，一键跳转项目源码仓库。

{
    "plugins": ["github"],
    "pluginsConfig": {
        "github": {
          "url": "https://github.com/你的用户名/你的仓库名"
        }
    }
}

添加页面源码编辑入口，读者可快速跳转仓库修改文档，适合开源协作文档。

{
    "plugins": ["edit-link"],
    "pluginsConfig": {
        "edit-link": {
          "base": "你的仓库编辑地址前缀",
          "label": "编辑本文"
        }
    }
}

back-to-top-button 回到顶部

添加悬浮回到顶部按钮，优化长页面浏览体验。

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

chapter-fold 标题折叠

点击侧边栏章节标题即可折叠/展开下级目录，比箭头折叠插件更简洁好用。

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

code 代码行号与复制

为代码块自动添加行号、复制按钮，支持自定义关闭复制功能。

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

在顶部导航栏自定义展示项目 Logo，提升文档品牌辨识度。

{
    "plugins": [ "insert-logo" ],
    "pluginsConfig": {
      "insert-logo": {
        "url": "logo图片地址",
        "style": "background: none; max-height: 30px; min-height: 30px"
      }
    }
}

主题美化插件

theme-default 默认主题

HonKit 兼容的官方默认主题，稳定适配所有插件，可开启目录层级数字编号。

{
    "plugins": [
      "theme-default"
    ],
    "pluginsConfig": {
        "theme-default": {
            "showLevel": true
        }
    }
}

theme-comscore 彩色主题

优化默认黑白样式，区分标题、正文颜色，页面层次感更强。

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

flexible-alerts 高亮提示块

将原生引用块转换为彩色提示框，支持 Note、Tip、Warning、Danger 四种类型，适配文档提示、警告、说明场景。

{
    "plugins": [
      "flexible-alerts"
    ],
    "pluginsConfig": {
      "flexible-alerts": {
        "style": "callout",
        "comment": {
          "label": "Comment",
          "icon": "fa fa-comments",
          "className": "info"
        }
      }
    }
}

使用示例：

> [!NOTE]
> 这是一条普通提示说明

theme-api 接口文档主题

专为 API 接口文档设计，支持暗黑模式，适配接口说明、参数展示场景。

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

theme-faq 问答主题

适配问答手册、常见问题文档，隐藏多余工具栏，聚焦问答内容展示，需搭配中文搜索插件使用。

{
    "plugins": [
        "theme-faq",
        "-fontsettings",
        "-sharing",
        "-search", 
        "search-plus"
    ]
}

插件开发规范

HonKit 插件基于 Node.js 开发，遵循 NPM 包规范，仅需补充 HonKit 专属配置字段，可自定义私有插件。

基础目录结构

最简插件必备两个文件：package.json（配置）、index.js（入口），复杂插件可扩展布局、静态资源、示例文档目录。

package.json 配置规范

包名必须以 gitbook-plugin- 开头，声明 HonKit 适配版本与自定义配置项。

{
    "name": "gitbook-plugin-mytest",
    "version": "0.0.1",
    "description": "自定义HonKit测试插件",
    "engines": {
        "gitbook": ">1.x.x"
    },
    "gitbook": {
        "properties": {
            "myConfigKey": {
                "type": "string",
                "default": "默认配置值",
                "description": "自定义配置说明"
            }
        }
    }
}

index.js 入口文件

通过钩子、代码块、过滤器实现插件功能拓展。

module.exports = {
    // 生命周期钩子函数
    hooks: {},
    // 自定义代码块语法
    blocks: {},
    // 内容过滤器
    filters: {}
};

私有插件引入

未发布到 NPM 的私有插件，可通过 GitHub 仓库地址直接引入使用：

{
    "plugins": [
        "myplugin@git+https://github.com/MyCompany/mygitbookplugin.git#1.0.0"
    ]
}

插件测试与发布

  • 本地测试：插件目录执行 npm link，文档目录执行 npm link gitbook-plugin-插件名 本地调试。
  • 正式发布：注册 NPM 账号，执行 npm publish 发布公共插件。

© lizhao all right reserved，powered by Gitbook文件修订时间： 2026-09-03 01:18:00

results matching ""

    No results matching ""