GitBook 插件实现顶部导航配置实战

GitBook 插件实现顶部导航配置实战

在技术文档建设中，顶部导航栏不仅是视觉元素，更是引导用户浏览路径的核心组件。针对 GitBook 的导航需求，我们通常有两种主流方案：轻量级的 NavBar 插件和更灵活的 theme-door 主题插件。下面结合实战经验，梳理它们的安装与配置细节。

1. NavBar 插件

这款插件主打极简风格，适合对导航要求不高的场景。

安装方式

由于官方仓库可能更新较慢，建议直接从源码获取。将代码克隆到项目的 node_modules 目录下即可：

cd node_modules
git clone https://github.com/jchamath/gitbook-plugin-navbar.git

配置说明

在 _config.yml 或 book.json 中启用插件并定义样式。核心配置包含 Logo 链接、菜单项以及颜色主题：

{
  "plugins": ["navbar"],
  "pluginsConfig": {
    "navbar": {
      "logo": {
        "link": "http://example.com/",
        "image": "http://example.com/resources/static/logo.png",
        "alt": "Example"
      },
      "menu": {
        "items": [
          { "text": "Home", "link": "http://example.com" },
          { "text": "Page", "link": "http://example.com/page/" }
        ],
        "style": {
          "color": "black",
          "hover": "#3579e2"
        }
      },
      "style": {
        "backgroundColor": "white",
        "linkColor": "black",
        "linkHoverColor": "blue"
      }
    }
  }
}

效果评估

整体界面干净清爽，但嵌入页面时显得略微生硬。主要限制在于无法隐藏导航条，且不支持下拉菜单功能。如果你追求的是'即插即用'的简单效果，这个方案足够用；若需要复杂交互，则需考虑其他方案。

2. theme-door 插件

这是一个功能更全面的主题方案，集成了 Header 导航、侧边栏（Sidebar）以及迷你地图（MiniMap）。

安装

推荐使用 npm 进行依赖管理，这样后续维护更方便：

npm i gitbook-plugin-theme-door

配置要点

该插件的配置较为丰富，涉及变量定义和插件组合。注意这里需要同时配置 variables 和 pluginsConfig，特别是 doorTheme 下的搜索占位符和 Logo 设置：

{
  "plugins": [
    "splitter",
    "hide-element",
    "code",
    "theme-door",
    "-lunr",
    "-search",
    "-sharing",
    "search-pro-fixed"
  ],
  "variables": {
    "doorTheme": {
      "nav": [
        { "url": "xxxxx", "target": "_blank", "name": "论坛" },
        { "url": "xxxxx", "target": "_blank", "name": "登录" }
      ]
    }
  },
  "pluginsConfig": {
    "hide-element": {
      "elements": [".gitbook-link"]
    },
    "doorTheme": {
      "search-placeholder": "请输入关键字搜索",
      "logo": "./_media/logo.svg",
      "favicon": "./_media/favicon.ico"
    }
  }
}

效果评估

相比前者，theme-door 提供了二次自定义开发的接口，灵活性更高。不过目前的默认主题在某些场景下不够友好，同样存在无法完全隐藏导航的问题，也不支持原生下拉菜单。如果团队有前端开发能力，基于此主题进行定制是一个值得投入的方向。

---

总结

选择哪种方案取决于你的具体需求。如果只需要基础导航，NavBar 插件最省事；如果需要高度定制化且具备一定开发资源，theme-door 更适合。无论选哪个，记得提前测试在不同分辨率下的显示效果，避免导航遮挡内容。