jeffrey-ng / honkit

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

Home Page:https://honkit.netlify.app

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

HonKit

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

HonKit Screenshot

Documentation and Demo

HonKit documentation is built by HonKit!

Quick Start

Installation

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

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:

Benchmarks

honkit build benchmark:

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

Deploys by Netlify

About

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

https://honkit.netlify.app

License:Apache License 2.0


Languages

Language:TypeScript 64.6%Language:JavaScript 14.3%Language:HTML 11.3%Language:Less 9.6%Language:Shell 0.1%Language:Dockerfile 0.1%Language:CSS 0.0%