jeffrey-ng / honkit

:book: HonKit is building beautiful books using Markdown - Fork of GitBook

HonKit

HonKit is building beautiful books using GitHub/Git and Markdown.

Documentation and Demo

HonKit documentation is built by HonKit!

• https://honkit.netlify.app/

Quick Start

Installation

• Requirement: Node.js LTS version

The best way to install HonKit is via NPM or Yarn.

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

⚠️ Warning:

• If you have installed honkit globally, you must install each plugins globally as well
• If you have installed honkit locally, you must install each plugins locally as well

We recommend installing honkit locally.

Create a book

HonKit can set up a boilerplate book:

$ npx honkit init

If you wish to create the book into a new directory, you can do so by running honkit init ./directory

Preview and serve your book using:

$ npx honkit serve

Or build the static website using:

$ npx honkit build

You can start to write your book!

For more details, see HonKit's documentation.

Docker support

Honkit provide docker image at honkit/honkit.

This docker image includes built-in dependencies for PDF/epub.

docker pull honkit/honkit
docker run -v `pwd`:`pwd` -w `pwd` --rm -it honkit/honkit honkit build
docker run -v `pwd`:`pwd` -w `pwd` --rm -it honkit/honkit honkit pdf

For more details, see docker/.

Usage examples

HonKit can be used to create a book, public documentation, enterprise manual, thesis, research papers, etc.

You can find a list of real-world examples in the documentation.

Features

• Write using Markdown or AsciiDoc
• Output as a website or ebook (pdf, epub, mobi)
• Multi-Languages
• Lexicon / Glossary
• Cover
• Variables and Templating
• Content References
• Plugins
• Beautiful default theme

Fork of GitBook

HonKit is a fork of GitBook (Legacy). GitBook (Legacy) is deprecated and an inactive project.

HonKit aims to smooth the migration from GitBook (Legacy) to HonKit.

Compatibility with GitBook

• Almost all plugins work without changes!
• Support gitbook-plugin-* packages
  • You should install these plugins via npm or yarn
  • npm install gitbook-plugin-<example> --save-dev

Differences with GitBook

• Node.js 14+ supports
• Improve build/serve performance
  • honkit build: use file cache by default
  • honkit serve: 28.2s → 0.9s in examples/benchmark
  • Also, support --reload flag for force refresh
• Improve plugin loading logic
  • Reduce cost of finding honkit-plugin-* and gitbook-plugin-*
  • Support honkit-plugin-* and @scope/honkit-plugin-* (GitBook does not support a scoped module)
• Remove install command
  • Instead of it, just use npm install or yarn install
• Remove global-npm dependency
  • You can use HonKit with another npm package manager like yarn
• Update dependencies
  • Upgrade to nunjucks@2, highlight.js etc...
  • It will reduce bugs
• TypeScript
  • Rewritten by TypeScript
• Monorepo codebase
  • Easy to maintain
• Docker support

Migration from GitBook

Replace gitbook-cli with honkit.

npm uninstall gitbook-cli
npm install honkit --save-dev

Replace gitbook command with honkit command.

  "scripts": {
-    "build": "gitbook build",
+    "build": "honkit build",
-    "serve": "gitbook serve"
+    "serve": "honkit serve"
  },

After that, HonKit just works!

Examples of migration:

• Add a Github action to deploy · DjangoGirls/tutorial
• Migrate from GitBook to Honkit · swaroopch/byte-of-python
• replace Gitbook into Honkit · yamat47/97-things-every-programmer-should-know
• Migrate misp-book from GitBook to honkit

Benchmarks

honkit build benchmark:

• https://honkit.github.io/honkit/dev/bench/

Licensing

HonKit is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

HonKit is a fork of GitBook (Legacy). GitBook is licensed under the Apache License, Version 2.0.

Also, HonKit includes bignerdranch/gitbook works.

Sponsors