Honkit插件介绍

HonKit 支持丰富的插件系统，允许你扩展功能（如自定义主题、添加搜索、支持数学公式等）。以下是 HonKit 插件的详细用法，包括常用插件介绍、安装、配置和注意事项。

1. 插件分类

HonKit 插件主要分为以下几类：

• 主题插件：修改文档外观（如 theme-default）。
• 功能插件：增强功能（如搜索、代码高亮、评论系统）。
• 输出格式插件：支持导出 PDF、ePub 等（如 honkit-plugin-pdf）。

2. 安装插件

通过 npm 安装插件，并在 book.json 中启用：

npm install honkit-plugin-<name> --save-dev

然后在 book.json 的 plugins 字段中添加插件名：

{
  "plugins": ["plugin-name1", "plugin-name2"]
}

3. 常用插件及用法

(1) 主题插件

• 默认主题（内置）
  
  配置示例：

  {
    "plugins": ["theme-default"],
    "pluginsConfig": {
      "theme-default": {
        "showLevel": true  // 显示标题层级
      }
    }
  }

• 第三方主题（如 theme-honkit）
  
  安装：

  npm install honkit-theme-honkit --save-dev

配置：

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

(2) 功能插件

① 搜索插件 (search)

启用即时搜索功能（默认已集成，无需安装）：

{
  "plugins": ["search"]
}

② 代码高亮 (highlight)

支持多种编程语言高亮（默认已启用）：

{
  "plugins": ["highlight"]
}

③ 数学公式 (mathjax)

支持 LaTeX 公式渲染：

安装：

npm install honkit-plugin-mathjax --save-dev

配置：

{
  "plugins": ["mathjax"]
}

用法：

行内公式：$E=mc^2$

块级公式：
$$
\sum_{i=1}^n i = \frac{n(n+1)}{2}
$$

④ 评论系统 (disqus)

集成 Disqus 评论：

安装：

npm install honkit-plugin-disqus --save-dev

配置：

{
  "plugins": ["disqus"],
  "pluginsConfig": {
    "disqus": {
      "shortName": "your-disqus-shortname"
    }
  }
}

(3) 输出格式插件

① 导出 PDF (pdf)

安装：

npm install honkit-plugin-pdf --save-dev

配置：

{
  "plugins": ["pdf"],
  "pluginsConfig": {
    "pdf": {
      "fontSize": 12,
      "paperSize": "a4"
    }
  }
}

生成 PDF：

honkit pdf

② 导出 ePub (epub)

安装：

npm install honkit-plugin-epub --save-dev

生成 ePub：

honkit epub

4. 插件配置

通过 book.json 的 pluginsConfig 字段自定义插件行为。例如：

{
  "plugins": ["my-plugin"],
  "pluginsConfig": {
    "my-plugin": {
      "key": "value"
    }
  }
}

5. 禁用插件

在 plugins 字段前加 - 可禁用插件：

{
  "plugins": ["-search"]  // 禁用搜索
}

6. 开发自定义插件

如果需要自定义插件，可参考 HonKit 插件开发文档，基本步骤：

1. 创建一个 npm 包，命名格式为 honkit-plugin-<name>。
2. 实现插件逻辑（如钩子函数）。
3. 发布到 npm 或本地引用。

7. 注意事项

1. 插件冲突：某些插件可能不兼容，需逐一测试。
2. 版本兼容性：确保插件支持当前 HonKit 版本。
3. 清理缓存：修改插件配置后，建议删除 _book 并重新构建：

   rm -rf _book
   honkit build

8. 官方推荐插件列表

通过插件系统，你可以轻松扩展 HonKit 的功能。更多插件可在 npm 搜索 honkit-plugin-* 或参考 HonKit 官方仓库。