GitBook（HonKit）入门篇

官方 GitBook 本地工具链已经停更。本文命令一律用 HonKit（社区 fork）。book.json、SUMMARY.md 和大部分 gitbook-plugin-* 仍能用，面向现行 Node.js。HonKit 官方的说法是几乎所有旧插件不用改就能跑。

这里有两套产品：

HonKit（接原来的本地工具链）：本机用 Markdown（也支持 AsciiDoc）写成书，输出静态站、PDF、ePub、mobi；
gitbook.com：在线文档托管，编辑、权限、GitHub 同步都在云上，和本地 HonKit 不是同一套管线。

前置准备

Markdown 快速入门

git - 简明指南

git --version
node --version

备注：HonKit 需要 Node.js 14+（用 LTS）。

本地安装 HonKit

HonKit 和插件必须装在同一范围：本地装 HonKit，插件也装本地。不要全局装 honkit 或 gitbook。没有 package.json 时先 npm init --yes。

npm install honkit --save-dev

package.json 脚本：

{
  "scripts": {
    "build": "honkit build",
    "serve": "honkit serve"
  }
}

之后用 npm run serve、npm run build，或 npx honkit。

常用命令

初始化

npx honkit init

空目录里会生成：

README.md：介绍，也是首页；
SUMMARY.md：侧栏目录，决定章节顺序。

指定目录：npx honkit init ./directory。

本地预览

npx honkit serve
npx honkit serve --port 4000

常见端口：

4000：浏览器打开 http://localhost:4000
35729：livereload 热更新

HonKit 默认缓存构建结果。插件装了却不生效时加 --reload：

npx honkit serve --reload

改 Markdown 后会重建，适合边写边看。

构建静态站点

npx honkit build
npx honkit build ./ ./docs

参数：

-o、--output：输出目录，默认 ./_book
-f、--format：site（静态站）、page、ebook、json
--config：配置文件，默认 book.json 或 book.js

输出目录里的 index.html 是入口，可放到静态服务器、GitHub Pages、Vercel 等。HonKit 没有 gitbook install，插件只用 npm install。

导出电子书

需要本机安装 Calibre，并且 ebook-convert 在 PATH 里。也可用官方 Docker 镜像（内带转换依赖）：ghcr.io/honkit/honkit。

npx honkit pdf ./ ./output.pdf
npx honkit epub ./ ./output.epub
npx honkit mobi ./ ./output.mobi

book.json

在项目根目录放 book.json（标准 JSON，不能写注释）。改完要重新 serve 或 build。

{
  "root": ".",
  "title": "我的一本书",
  "page": {
    "title": "前端知识库(lizh)"
  },
  "author": "lizhao",
  "description": "",
  "language": "zh-hans",
  "variables": {
    "authorName": "lizhao"
  },
  "structure": {
    "readme": "README.md",
    "summary": "SUMMARY.md",
    "glossary": "GLOSSARY.md",
    "languages": "LANGS.md"
  },
  "plugins": [
    "anchors",
    "expandable-chapters-small",
    "search-plus",
    "toggle-chapters",
    "summary",
    "splitter",
    "theme-comscore",
    "fontsettings",
    "-lunr",
    "-search"
  ],
  "pluginsConfig": {
    "expandable-chapters-small": {},
    "fontsettings": {
      "theme": "white",
      "family": "sans",
      "size": 2
    }
  },
  "links": {
    "sidebar": {}
  },
  "styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
  }
}

字段：

root：源码目录，相对 book.json，默认 .；
title、author、description：书名、作者、简介。顶层 title 才是官方书名；page.title 给部分主题、插件用；
language：页面语言，zh-hans 为简体中文；
structure：Readme、目录、词汇表、多语言清单的文件名，后两个可选；
plugins：插件名；前面加 - 表示关掉默认插件；
pluginsConfig：插件参数；
links.sidebar：侧栏额外链接；
styles：覆盖网站、电子书 CSS。

不必再写 "gitbook": "3.2.3"，那是给官方 CLI 选引擎用的。

GitBook 3 默认带 highlight、search、sharing、fontsettings、lunr，serve 时还有 livereload。中文搜索常关掉自带 search、lunr，改用 search-plus。

备选：search-pro、back-to-top-button、chapter-fold、page-treeview。部分旧插件在现行 Node 上会安装失败或构建失败，以 npm install 的结果为准。

插件使用

命名规范：

功能：gitbook-plugin-xxx
主题：gitbook-theme-xxx
HonKit 另认 honkit-plugin-* 和带 scope 的 @scope/honkit-plugin-*

安装步骤：

在 book.json 的 plugins 里声明；
npm install gitbook-plugin-xxx --save-dev；
需要参数时写 pluginsConfig；
npm run serve 或 npm run build。缓存作怪就加 --reload。

{
  "plugins": ["myPlugin"],
  "pluginsConfig": {
    "myPlugin": {}
  }
}

gitbook.com 与 GitHub

本地 HonKit 和 gitbook.com 不是同一套管线：HonKit 在本机把 Markdown 编成静态站；官网用自己的编辑器和主题托管文档。两边要「一份源码、两处更新」，中间枢纽是 GitHub。

和 GitHub 的互动有两条路：

Git Sync（源码同步）：GitHub 仓库里的 Markdown 和 gitbook.com 上的空间双向同步。开发者在仓库里改 .md，写作者在 GitBook 编辑器里改，最后都落到同一个 GitHub 分支。
GitHub Pages（构建产物）：本机 honkit build 得到 _book，把静态文件推到 GitHub 再打开 Pages。这是托管 HTML，不经过 gitbook.com。

同一仓库可以同时做两件事：源码目录给 Git Sync；honkit build ./ ./docs 之后把 GitHub Pages 指到 /docs（或单独用 gh-pages 分支）。不要把 _book、docs 和源码塞进 Git Sync 同步的同一个目录，否则官网会把构建产物当文档。

Git Sync 在做什么

装上 GitBook GitHub App 并选定仓库、分支之后：

在 GitHub 上每推一次（或合并一次 PR），gitbook.com 空间按提交更新；
在 GitBook 里合并一次变更请求（Change request），会往该分支打一次 commit；
目录以仓库里的 SUMMARY.md 为准。GitBook 编辑器改了侧栏，也会回写 SUMMARY.md。没有 SUMMARY.md 时，官网会按文件夹结构推断，并在之后自己生成、维护这份目录。

仓库根或文档子目录可放 .gitbook.yaml，用 root、structure.readme、structure.summary 指到真实路径。字段含义接近 HonKit book.json 里的 structure，但 Git Sync 读的是 .gitbook.yaml，不会去执行 book.json 里的插件和主题。HonKit 插件只作用于本地 _book，不会出现在 gitbook.com 页面上。

第一次接通时要选同步方向：

GitHub → GitBook：仓库里已有 Markdown，同步到空的空间；
GitBook → GitHub：空间里已有内容，写进空仓库或空分支。

之后就是双向。两边同时改同一段，会像普通 Git 一样冲突，需要在 GitHub 或 GitBook 里解开后再同步。

公开仓库若没把 GitBook App 授权到该仓库，常见现象是 GitHub → GitBook 能进，反向推不回去。到 GitHub 组织的 Applications 里给 GitBook 补上仓库权限。GitHub Enterprise Server 目前用不了这套官方 App。只有空间的管理员、创建者能开 Git Sync。