In this article, we’ll show you how to install Honkit in a local folder and how to use it to create a simple project.
Honkit is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc). Follow the link for the Honkit project.
Honkit is a fork of GitBook, which is an excellent tool for creating documentation, but it now has a compatibility issue with recent Node.js versions. The author of this article attempted but was unable to install GitBook on a Docker Desktop local folder. Then he tried Honkit and quickly installed it.
Honkit can output your content as a website (customizable and extensibles) or as an ebook (PDF, ePub or Mobi).
Install Honkit in Local Folder
Create a folder for a Honkit project, navigate to it, and execute the CLI command to install Honkit libraries:
npm install honkit --save-devTo create a Honkit project with all the necessary files, run the command:
npx honkit init
Ensure that all the files created and run the command to launch Honkit application:
npx honkit serveAfter launching of the Honkit application you are offered:
Serving book on http://localhost:4000Copy this URL and paste in a browser’s address filed, you will see your Honkit project initial state:
You can get plugins from the npmjs site. Find the words honkit-plugin and gitbook-plugin in the search.
How to Create Honkit Project
This section will demonstrate how to create a simple Honkit project. The project is simple and simultaneously contains the main features of Honkit.
Install Honkit as described above and create a folder for it, for example, honkit-project. Create some basic project files in this folder:
- The file
package.jsonto install the Node.js dependencies:
{
"name": "sample-book",
"description": "Sample book demonstration",
"version": "0.0.1",
"dependencies": {
"gitbook-plugin-api-language-selector": "git+https://github.com/algorithm-archivists/gitbook-plugin-api-language-selector.git",
"gitbook-plugin-bibtex-cite": "git+https://github.com/algorithm-archivists/gitbook-plugin-bibtex-cite.git",
"gitbook-plugin-bulk-redirect": "^0.2.1",
"gitbook-plugin-codeblock-label": "^1.0.1",
"gitbook-plugin-collapsible-menu": "*",
"gitbook-plugin-ga": "^2.0.0",
"gitbook-plugin-github": "2.0.0",
"gitbook-plugin-heading-anchors": "^1.0.3",
"gitbook-plugin-include-codeblock": "^3.2.2",
"gitbook-plugin-language-picker": "^0.1.0",
"gitbook-plugin-mathjax": "git+https://github.com/algorithm-archivists/plugin-mathjax.git",
"gitbook-plugin-prism": "^2.4.0",
"gitbook-plugin-richquotes": "0.0.9",
"gitbook-plugin-sectionx-ex": "*",
"gitbook-plugin-wordcount": "^0.0.1",
"honkit": "^3.6.16"
},
"license": "MIT",
"scripts": {
"build": "honkit build",
"serve": "honkit serve"
}
}
- The file
book.json, which is the Honkit project configuration file:
{
"honkit": ">= 3.0.0",
"root": "./sample-book",
"title": "Sample Book",
"plugins": [
"language-picker",
"api-language-selector@https://github.com/algorithm-archivists/gitbook-plugin-api-language-selector.git",
"include-codeblock",
"prism",
"-highlight",
"codeblock-label"
],
"api-language-selector": {
"languages": [
{
"lang": "bash",
"name": "Bash"
},
{
"lang": "cs",
"name": "C#"
},
{
"lang": "py",
"name": "Python"
},
{
"lang": "js",
"name": "JavaScript"
},
{
"lang": "java",
"name": "Java"
},
{
"lang": "php",
"name": "PHP"
},
{
"lang": "ts",
"name": "TypeScript"
}
]
},
"pluginsConfig": {
"github": {
"url": "https://github.com/DjangoGirls/tutorial"
},
"language-picker": {
"grid-columns": 3
},
"include-codeblock": {
"fixlang": true,
"unindent": true
}
}
}- The file
LANGS.md, which specifies the code languages to switch:
# Languages
* [Bash](bash/)
* [C#](cs/)
* [Python](py/)
* [JavaScript](js/)
* [Java](java/)
* [PHP](php/)
* [TypeScript](ts/)- The file README.md, which is main introduction section of the project:
# Introduction
Main introduction- The file
SUMMARY.md, which is the navigator of the Honkit project:
# Summary
* [Introduction](README.md)
* [Chapter 1](Chapter1/README.md)
* [Article 1-1](Chapter1/Article1-1.md)
* [Article 1-2](Chapter1/Article1-2.md)
* [Chapter 2](Chapter2/README.md)
* [Article 2-1](Chapter2/Article2-1.md)
* [Article 2-2](Chapter2/Article2-2.md)Take note of the indentations in the content – this is how the project’s left menu hierarchy is specified.
Make the sample-book folder in the root folder. You can create all the book folders and files in the root folder, but in separate folders is more convenient, because you can put another book folder in the root folder and switch between them. That is why we specified it in the book.json file "root": "./sample-book".
Create folders and files in “sample-book” as:
sample-book
-- folder Chapter1
-- folder code
-- folder cs
-- file sum.cs
-- folder java
-- file sum.java
-- file Article1-1.md
-- file Article1-2.md
-- file README.md
-- folder Chapter2
-- file Article2-1.md
-- file Article2-2.md
-- file README.md
The README.md files in the chapter sub-folders serve as introductions to the chapters.
In the file Article1-1.md write:
# Article 1 In Chapter 1
This article 1 in the chapter 1.
{% method %}
{% sample lang="cs" %}
[import, lang:"cs"](code/cs/sum.cs)
{% sample lang="java" %}
[import, lang:"java" ](code/java/sum.java)
{% endmethod %}In the rest article write what ever your want.
Now execute the CLI command:
npx honkit serve Enter http://localhost:4000 in a browser’s address field. You are expect to see:
Click on Article 1-1:
Take note that in this article you are able to switch code language.
You can examine or download the full honkit-sample-project project from this link.
Was this helpful?
3 / 0