HonKit: a GitBook fork for turning Markdown into books and docs

The gap HonKit fills: GitBook (Legacy) is deprecated

GitBook (Legacy) is deprecated and inactive, which left a set of books and manuals built on a tool with no upstream. HonKit is a fork of that codebase, and the README states its aim plainly: to smooth the migration from GitBook (Legacy) to HonKit. That is the specific problem. People did not lose interest in writing books in Markdown, they lost the tool that compiled them.

The audience is narrow and identifiable. It is teams with a gitbook build step in CI, a book.js configuration file, and plugins published as gitbook-plugin-* on npm. HonKit also targets anyone who wants a single Markdown source to produce a website and an ebook, since the feature list includes website output plus pdf, epub and mobi. If you are starting fresh with no legacy content, the migration story means nothing to you, and the rest of this article is about whether the tool stands on its own.

How the build pipeline works, and where the cache sits

The repository is a pnpm monorepo. The root package.json is private and named honkit-root, with packages/ holding the workspace members, and the root devDependencies pull honkit from the workspace itself. The CLI was rewritten in TypeScript, and the README lists that rewrite alongside a monorepo layout as a maintenance difference from GitBook.

The visible behavioural difference is caching. According to the README, honkit build uses a file cache by default, and honkit serve reports 28.2s to 0.9s in examples/benchmark. Those numbers come from the project's own benchmark directory, not from an independent run, so treat them as the project's claim rather than a measured result. The --reload flag forces a refresh, which is the escape hatch when the cache serves something stale.

Plugin loading is the other mechanism the README calls out. HonKit reduces the cost of finding honkit-plugin-* and gitbook-plugin-* packages, and it supports scoped names in the form @scope/honkit-plugin-*, which the README says GitBook does not support. That scoped support is the difference between publishing under your own npm scope and squatting on a flat name.

Install HonKit and build a first book

HonKit needs Node.js LTS. The README recommends installing it locally rather than globally, and pairs that with a warning: a global honkit requires globally installed plugins, and a local honkit requires locally installed plugins. Mixing the two is the most common way to get a plugin that refuses to load.

Start a project and add HonKit as a dev dependency:

npm init --yes
npm install honkit --save-dev

Generate the boilerplate. The README shows honkit init, and notes that honkit init ./directory creates the book in a new directory instead:

npx honkit init

Serve it locally while you write. This is the command where the file cache matters most, because it is the one you run repeatedly:

npx honkit serve

Build the static site when you want output on disk:

npx honkit build

If you would rather not install Node.js at all, the README documents a Docker image at ghcr.io/honkit/honkit and states that it includes built-in dependencies for PDF and epub. The example mounts the current directory and runs the build inside it:

docker pull ghcr.io/honkit/honkit
docker run -v `pwd`:`pwd` -w `pwd` --rm -it ghcr.io/honkit/honkit honkit build

Swapping honkit build for honkit pdf in that same command produces the PDF, per the README. The Docker route is also the answer for anyone whose host machine lacks the native libraries the PDF and epub pipeline expects.

Plugins: the compatibility promise and its edges

The README claims almost all plugins work without changes and that gitbook-plugin-* packages are supported. Install them the ordinary way:

npm install gitbook-plugin-<example> --save-dev

That compatibility is the reason to pick HonKit over a newer generator, and it is also the largest source of risk. Plugins written against GitBook (Legacy) may reach into internals that a TypeScript rewrite and upgraded dependencies changed. The README notes upgrades to nunjucks@2 and highlight.js among the dependency updates, and calls out that this reduces bugs. A plugin that depended on the older nunjucks behaviour is exactly the case where "almost all" stops being all.

The README does not document a rollback path if a migrated plugin misbehaves, and it does not list which plugins are known to break. The practical check is to install your plugin set and run honkit build before you delete the old tooling from CI.

What HonKit does not do

HonKit has no install command. The README lists its removal as a deliberate difference from GitBook, with the instruction to use npm install or yarn install instead. Anyone following an older GitBook tutorial that runs gitbook install will find the equivalent command missing, and the fix is to declare plugins in package.json like any other dependency. The same applies to the removed global-npm dependency, which the README says frees you to use yarn or another package manager.

There is a second boundary. HonKit is a documentation and book generator, not an application framework. It renders Markdown and AsciiDoc into a themed site with a sidebar and search, and it does not give you a component model for building interactive pages. If your documentation site needs custom React components in the middle of prose, this is the wrong tool, and no plugin will turn it into one.

The project's own documentation site is built with HonKit, which is a reasonable signal that the tool is used for its intended purpose, though it says nothing about edge cases.

MdBook and Docusaurus as the two real alternatives

MdBook is the closest match in scope. It is a Rust binary that compiles Markdown into a static book with a similar chapter-and-sidebar structure. The difference is the extension model: MdBook has its own preprocessor and renderer concepts, so a GitBook plugin cannot be reused. If your book has no plugins, MdBook gives you a single binary with no Node.js runtime to manage. If it has plugins, that portability is worthless to you.

Docusaurus goes the other direction. It is a React-based site generator where documentation is one content type among several, and pages are composed from components. That buys you a blog, versioned docs and custom interactive pages. It costs you the GitBook plugin ecosystem and the single-source ebook output. HonKit's feature list includes PDF, epub and mobi from the same Markdown, and that is the capability Docusaurus does not offer out of the box.

Choosing between them comes down to one question: do you need the ebook formats and the legacy plugins, or do you need a component model? HonKit answers the first, Docusaurus the second, and MdBook sits in between with a smaller extension surface.

Licence, maintenance and upgrade cost

HonKit is licensed under Apache-2.0, and the README states that GitBook (Legacy) carries the same licence, as does the bignerdranch/gitbook work that HonKit incorporates. Apache-2.0 includes an explicit patent grant and requires that you retain notices. If you redistribute a built book or a modified HonKit, the notice obligations apply. That is a description of the licence text, not legal advice; read LICENSE in the repository if redistribution is part of your plan.

The repository is not archived, and the last push was on 2026-09-13. The release history shows v6.2.0, v6.2.1 and v6.2.2 between May and June 2026, so the version line is moving. The root package.json pins the package manager to [email protected], and a versionup script refuses to run locally, directing contributors to a create-release-pr workflow instead. That means releases come from CI, which is a detail worth knowing if you build from a fork.

Upgrade cost sits mostly in the plugins, not in HonKit itself. Because the plugin API is inherited from a deprecated project, a plugin that has not been touched in years is the component most likely to break on a Node.js LTS bump. The build cache also means an upgrade can leave stale artifacts behind, and --reload is the documented way to force a refresh.

Editorial conclusion

HonKit fits teams with an existing GitBook (Legacy) book, custom gitbook-plugin-* packages, or a need for PDF and epub output from the same source as the site. It is a poor fit if you want a component-based site generator or a project that does not depend on the legacy GitBook plugin API. Before migrating, verify that every plugin you rely on resolves under the HonKit loader, and check whether your build runs on Node.js LTS as the README requires.

Frequently asked questions

Official sources

1. honkit/honkit on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases