honkit/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

honkit's Issues

test: integration test

In my experience, integration test is useful on large CLI project.
The best is that use actual project for testing.
It help us to find regression bug.

e.g. https://github.com/textlint/textlint/tree/master/test/integration-test

HonKit output is HTML,JS,CSS files.
So, We can add snapshot testing using actual project.

However, snapshot file(Its just _book dir) is large. I think we have to come up with a good idea.

Start to small example project, Use GitHub Actions and artifact, put separacted repository...

gitbook-plugin-uml does not work

Summary

https://github.com/vowstar/gitbook-plugin-uml does not work on Honkit

• HonKit version: 3.3.10

Step to reproduce

• Link to code example: https://github.com/azu/honkit-example-gitbook-plugin-uml

Expected results

Render the uml correctly.

Actual results

Rendering error.

Note

https://github.com/vowstar/gitbook-plugin-uml/blob/99ad7443d2a2c051c2327c7ebda63a0ca19f1621/index.js#L41
Dump the code variable and I noticed the differnece between GitBook and HonKit

GitBook

@startuml

    Class Stage
    Class Timeout {
        +constructor:function(cfg)
        +timeout:function(ctx)
        +overdue:function(ctx)
        +stage: Stage
    }
    Stage <|-- Timeout

@enduml

HonKit

@startuml

```
Class Stage
Class Timeout {
    +constructor:function(cfg)
    +timeout:function(ctx)
    +overdue:function(ctx)
    +stage: Stage
}
Stage <|-- Timeout
```

@enduml

TypeScript: target is es2018

HonKit support Node.js LTS - Node.js 10+.

• https://github.com/nodejs/Release

So, we need to change tsconfig.json's target to es2018 or es2017.
(Node.js 10 does not suppor ES2019)

honkit/tsconfig.json

Line 3 in b9267fc

"target": "es2019",

https://node.green/#ES2017
https://node.green/#ES2018

It is part of TypeScript migration #24 .

📝 Currently, HonKit code does not use ES2019 features and it is not problem.
Also, TypeScript only transpile syntax.

plugin theme prefix

githon- prefix support

Front Matter's title reflect to `<title>`

---
titile: "page title"
---

do reflect to <title>.
It is reasonble, I think.
Currently, It is just page variable.

honkit plugin + scoped module is not loaded

Summary

@scope/honkit-plugin-xxx is not loaded

• HonKit version: lastest

Step to reproduce

@ansanloms/honkit-plugin-uml is not loaded.

• Link to code example: https://github.com/ansanloms/honkit-test

Expected results

@ansanloms/honkit-plugin-uml is load as honkit plugin

Actual results

@ansanloms/honkit-plugin-uml is just ignored.

hontkit build --reload does not work

jaredwray/flat-cache#21
flat-cache issue

default-theme: add updated-time

Add updated time to footer.

locateRootFolder.js issue

https://github.com/azu/githon/blob/bfef79bd2957b8214eb052e376877187e71d8692/packages/githon/lib/plugins/locateRootFolder.js#L17 logis has an issue.

Probably, it will broken.

performance benchmark

need speed

improve serve

seeve stop and go.
it slow down

Is there a way to auto generate summary.md?

Is there an easy way to autogenerate summary.md based off folder structure?

Logo/Icon

Currently, This project used my rough sketch

https://www.figma.com/file/gOGzd8OgSLMj2P43sH9lBG/HonKit?node-id=0%3A1

This is related with concept #12

We need to improve this design.

Uncertain use of Git name trademark

It seems that Git committee doesn't approve of the use as part of the name in projects not affiliated with them.

There is a lengthy discussion on mailing list here
https://public-inbox.org/git/[email protected]/

and their written guidelines
https://www.git-scm.com/about/trademark

Maybe something with "Book" word could be a better name?

udpate jquery

Use Buffer.from

https://github.com/azu/githon/blob/3de1998203e58cad4c646a678d11cb47645ffbbc/packages/githon/lib/fs/mock.js#L51

supress deprecated warning

(node:37612) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.

perf: worker_threads

honkit build bottleneck is template rendering.

https://github.com/honkit/honkit/tree/3de1998203e58cad4c646a678d11cb47645ffbbc/packages/githon/lib/templating

Worker Threads make honkit fast?

remove global-npm

githon will not depended on npm.
should work yarn too

Support `honkit` variables

Currently, we only provide gitbook varaibles.

We need to provice honkit variables as same value.

• https://honkit.netlify.app/templating/variables.html

📝 gitbook variables will be preserved for backward compatible. It can not be deleted.

Reduce Immutable.js

Reduce usage of Immutable is meaningful.

Immutablity is good, but Immutable.js is hard.

• Immutable.js block worker thread support #37
  • Need to Serialize/Deserialize between immutable.js and JavaScript
• Immutable.js project status is unclear immutable-js/immutable-js#1689
• Pure ECMAScript expressive power is grown

Immutable is important, but base class should not base on JavaScript framework like Immutable.js.
Pure domain object model is better and use helper library is ok.
For example, immutable-array-prototype help model to manupulate array as immutable.

Docker support

We need to provide docker image.

Would be nice like that

$ docker run --rm -it honkit/honkit honkit build
$ docker run --rm -it honkit/honkit honkit serve
$ docker run --rm -it honkit/honkit honkit pdf # need ebook-convert 

📝 Need to publish from CI like https://github.com/secretlint/secretlint/blob/master/.github/workflows/publish-artifact.yml
Dependency order: publish npm → push Docker Image

UseCase

• Non-Node.js user easy to use HonKit
• Use Docker Image instead of installing ebook-convert into globally

docs: community driven

add phylosopy for githon

3.3.9 build fail , theme-default version detect error?

Report:

Try convert from gitbook to githon.
https://github.com/tsuyoshicho/WhenScarletIceMelted/tree/feature/githon

Setup and npm install success for githon 3.3.9 and others.

But, when npm run build(githon build) phase, error occur.

Platform: Windows, Linux
Node: v14.4.0

`Githon doesn't satisfy the requirements of this plugin: >=4.0.0-alpha`

WhenScarletIceMelted on  feature/githon via ⬢ v14.4.0 took 15s
⏰[ 2020-06-20T07:40:09 ] ❯ npm install

> [email protected] install D:\Data\ReposWork\git\WhenScarletIceMelted\node_modules\node-sass
> node scripts/install.js

Cached binary found at C:\Users\tsuyoshi\AppData\Roaming\npm-cache\node-sass\4.14.1\win32-x64-83_binding.node

> [email protected] postinstall D:\Data\ReposWork\git\WhenScarletIceMelted\node_modules\node-sass
> node scripts/build.js

Binary found at D:\Data\ReposWork\git\WhenScarletIceMelted\node_modules\node-sass\vendor\win32-x64-83\binding.node
Testing binary
Binary is fine
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

added 788 packages from 768 contributors and audited 790 packages in 378.876s

60 packages are looking for funding
  run `npm fund` for details

found 3 vulnerabilities (1 low, 2 high)
  run `npm audit fix` to fix them, or `npm audit` for details
WhenScarletIceMelted on  feature/githon via ⬢ v14.4.0 took 6m20s
⏰[ 2020-06-20T07:46:34 ] ❯ npm run build

> [email protected] build D:\Data\ReposWork\git\WhenScarletIceMelted
> githon build

info: 9 plugins are installed
info: 9 explicitly listed
info: plugin "creativecommons is loaded
info: plugin "styles-sass-fix is loaded
info: plugin "puml is loaded
info: plugin "highlight is loaded
info: plugin "search is loaded
info: plugin "lunr is loaded
info: plugin "fontsettings is loaded
info: plugin "theme-default is loaded
Githon doesn't satisfy the requirements of this plugin: >=4.0.0-alpha
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build: `githon build`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\tsuyoshi\AppData\Roaming\npm-cache\_logs\2020-06-19T22_46_47_721Z-debug.log
exit status 1
WhenScarletIceMelted on  feature/githon via ⬢ v14.4.0 took 2s
⏰[ 2020-06-20T07:46:47 ] ❯

default-theme: Drop jQuery

We can drop jQuery.
Because, support browser is modern browser.

self document

Embed font on PDF

GitbookIO/gitbook#1445

perf: why nunjucks noCache: true?

According my profile, a bottoleneck of honkit build is nunjucks render
#37 worker_thread issue is for that.

I've notices that honkit pass noCache: true to nunjucks. Is it really? (Need to confirm!)

honkit/packages/honkit/src/templating/themesLoader.js

Line 37 in 025344d

noCache: true,

If we will set noCahe: falase, we can make honkit build more fast.

https://mozilla.github.io/nunjucks/api.html#configure

TODO

• Add profile data: node --inspect --inspect-brk is useful
• noCache: true is actual used?
  • If it is actual used, why?
• Change noCache: false if it is possible

Code in Table

It is regression?

import external package into the monorepo

• import gitbook-* to monorepo
• parsers #9
• https://github.com/GitbookIO/markup-it
• theme

Algolia DocSearch Integration

https://docsearch.algolia.com/ is awesome search engine.
We want to get DocSearch Integration as built-in feature. It will be built-in plugin or theme.

Related: https://v2.docusaurus.io/docs/search/

support githon-plugin-*

githon-plugin-* prefix and @scope/githon-plugin-* support

docs: githon-plugins-* prefix

#20 implemented. we need to add these to doc.

docs: concept

• Stability
• Maintenanceability
• Durty hacks but extensiblity

GitHon not aim to get cool features, I think.

add "clean" command for each packages

cleanup before build

Issue Template

we need to get Bug reporting template

• version
• book.js
• log
• minimal reproduce repo

Add note about GitBook deprecation and why fork?

• GitbookIO/gitbook@6c6ef7f
• GitbookIO/gitbook#2170

TypeScript

We want to convert codebase to TypeScript.

Transfer to GitHon org

We have got githon organization.
We need to rewrite pacakge's repositories.

New default theme

We consider to new default theme.
Probably, @honkit/honkit-plugin-theme-default(current theme) is still existing in the future for compatiblity.

We want to opt-in new default theme.
It is probably a mechanism that is enabled by adding some settings to book.json.

Releated idea: label:"Type: Theme"

Purpose

• Fast
• Stable
• Extensible

Changes from current default theme

• Reduce Cumulative Layout Shift #91
  • Remove Sidebar layout storage
  • Remove Font Settings
  • Rendering as server-side, less client-side rendering
• Reduce library like jQuery
  • But plugins depend on jQuery...
• Reduce dependency
  • Remove font-awesome #132
• Use <a> link instead of Pjax

TODO

• Built-in Search
• Plugin Compatibility
  • It will probably never be fully compatible. It will provide alternative functions.
• Opt-in Switch
• Async Loading for INP
• View Transition API support?

Usage

• See #57 (comment)

HonKit next

Next HonKit major ideas.

It is breaking changes list!

Todo

• remove asciidoc support MayBe.

Migrate from GitHon to HonKit

GitHon is renamed to HonKit because GitHon has Git trandmark issue #48 #52

Migration from GitHon to HonKit

1. Install honkit instead of githon

npm uninstall githon
npm install honkit -D

2. Replace githon command with honkit command.

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

Examples

• chore(deps): use HonKit instead of GitHon by azu · Pull Request #1189 · asciidwango/js-primer

defalut theme

create dedault theme for githon

Drop Q

We want to remove Q wrappper.
https://github.com/azu/githon/blob/master/packages/githon/lib/utils/promise.js

We should use Promise instead of Q.

Pros

• Async Function compatibility
• Less code base
• Performance

Cons

• Refactoring time

TODO

• How to migrate?

CI: cross platform tests

add Windows, macOS

docs: publishing

We should creat "Publishing" page on docs.

Publish to GitHub Pages or Netlify, and more.

Move https://honkit.netlify.app/faq.html faq to separated page.

plugin loading perf issue

https://github.com/azu/githon/blob/3de1998203e58cad4c646a678d11cb47645ffbbc/packages/githon/lib/plugins/findInstalled.js

It will very slow.
use require.resolve instead of recursive search.

Rename to HonKit in code base

We should use "HonKit" name in our code base.
Some code and docs still use original name.

honkit/packages/honkit/src/output/ebook/getConvertOptions.js

Lines 29 to 30 in ef55687

	"--book-producer": "GitBook",
	"--publisher": "GitBook",

📝 Note

honkit variables does not implemented yet #36

Welcome to Contributors!

HonKit project always welcome to new contributors! ✋

Multiple maintainer make this project more stable!

Contributing way is various

• Improve documentation
• Fix a bug
• Add a new feature

If you interesting in HonKit, please see contributing guide!

• https://github.com/honkit/honkit/blob/master/CONTRIBUTING.md

Welcome to contribute!

Also good first issue is available!

Rename GitHon to HonKit

Acording to #48, Git is trandmark

• About - Git

So, we need to rename GitHon project to avoid this issue.

Edit:

We have decided to rename GItHon to HonKit.

Todo

• GitHub Organization
• Netlify https://honkit.netlify.app/
• Source Code & package.json
• Documents
• npm
  • maybe deperecated old name #54
• Blog
  • https://efcl.info/2020/06/19/githon/

User Affects

Probably, https://github.com/githon/ is 404.

• npm package is still aliave

Bibliography?

Hi, I have searched for the term "bibliography" in the docs with no avail.
Does honkit support some kind of bibliography?
Similar to LaTeX I mean, the environment I use nowadays, I have tons of .bib files...
Thank you