How to create Documentation for your next hacking tool using Honkit GitBook! Step by Step Guide

9 min readApr 8, 2024

Documentation is the most important piece of your effort in building your hacking tool. It is the text that users will most refer to when in need of help, whether it is for setting up and installing your tool or for usage examples of your tool. Documentation is the go-to for most users, so creating neat, clean, and straight-forward documentation is as important as building a stable and reliable tool for reaching most users. So today I’m going to show you my favorite tool for building neat and clean documentations for my tool — Honkit.

What is Honkit?

Honkit is a fork of the legacy GitBook (an older version of the GitBook platform, which was a popular tool for writing and hosting documentation). So, without further ado, let’s jump right into installing and setting up Honkit.

Navigate to the directory where we want to build the documentation and run the following command -

npm install honkit --save-dev

After that run npx honkit initto initialize the directory with honkit project. After that run

npx honkit build

npx honkit serve

to start the local server to see the actual website.

Building & Serving inital Honkit website

Note: if we don’t want to run npx command then we can add following lines in package.json file found in root directory

"scripts": {
    "build": "honkit build",
    "serve": "honkit serve"
  }

This will allow us to build and serve the GitBook using npm run build and npm run servefrom now, I will use these two commands.

The result will be empty gitbook which we will fill with our tool’s documentation.

The SUMMARY.md file

Now it’s time we will open this directory into VS Code.

The SUMMARY.md file will serve as table of contents as navigation menu for our documentation. We need to add all of the parts and sections of our documentation. So just outline the sections that are going to be in our documentation and mention them here as follows —

Here I have added parts Introduction, Installation, Usage Manual, Fuzzing Using BrowserBruter and Contribution. I have also mentioned sections in [name](path/to/mdfile.md) format such as first one BrowserBruter and last is Contribution and mentioned their respective README.md file. Just like above think and outline the parts and sections of our documentation in SUMMARY.md file and save it.

The result will be various sections added into navigation menu.

Directory Structure

After outlining sections, we have to create their respective files. The inital gitbook directory will be empty, we have to create new directories as chapters and create new markdown files for each chapters like following —

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

In our tool’s documentation, chapters can be — 1. Introduction, 2. Setup & Installation, 3. Usage Examples, etc. So let’s create various directories as chapters for our tool’s documentation.

Here each directory is individual section of our documentation. Create README.md for each section.

Then create respective markdown file for each unique topic we have outlined in SUMMARY.md i.e. for Attack Modes I have created attack.md —

Before creating this structure, we must have a clear vision of how we want to structure the content of our tool’s documentation. For example, I have structured it as follows: 1. Introduction about my tool, 2. Why and when to use my tool, 3. Setup & Installation of my tool, 4. Usage Examples and Explanation of available options, 5. Some advanced usage examples, 6. How to contribute to the tool. Based on our requirements, we might want to structure our documentation differently. So, first, get a clear vision of the structure of the documentation, then begin creating sections and parts.

The book.json file

This file allows us to configure various attributes of our GitBook. The options are comprehensive. But for our tool’s documentation, we will not require much configuration. However if we want to add something in this file, we can add following —

Here we have specified title, author and description of our GitBook. We can find comprehensive list of configuration options here. This file must reside in the root directory of our GitBook.

The GLOSSARY.md

The GLOSSARY.md file contains terms and their definitions. We might want to create this file in case we want to explain any confusing term with ease. For example, we want to explain what is ‘selenium-wire’ package of python, we can do it as follows -

Here, I have created definition for term ‘Selenium-Wire’. Now wherever this term appears in our documentation, the ‘?’ character will appear which will provide its definition as follows —

Adding Images and gifs

To add images or gifs, we have to create a directory called ‘img’ in root directory of our project where all of our images will reside. Then same as any markdown syntax we have to add them in our page as follows-

And the result will be as follows —

Note: I am using ‘peek’ utility to quickly capture gifs of my screen recording. This is extremely useful and comes handy while demonstrating working of tool visually. We can install ‘peek’ utility using following command — ‘apt install peek’. More information on peek can be found here.

Or you can just directly copy and paste the images where you want them as follows —

Adding Videos

Adding short video clips to live demonstrate working of our tool can be really helpful for users or our tools to better understand the working of tool plus it will be a graphical nice touch in our documentation.

I would suggest using OBS Studio for recording you screen. Install it using sudo apt install obs-studio and make output format as .mp4 to include it in our documentation.

Note: you can set shortcut hotkeys for starting and stopping the recording so you don’t need to worry about manually clicking on start recording and stop recording button. For example here’s mine hotkeys shortcut for starting and stopping recording -

Hotkeys for starting & stopping recording

Record the video and add it using following block of code —

<video controls style="width: 100%;">
    <source src="img/basic-navigation-1.mp4" type="video/mp4">
    Your browser does not support the video tag.
</video>

And following will be the result —

At this point, our project structure should look like as follows -

Now we had outlined the structure of our documentation and now we start filling these empty files to prepare our documentation.

Basic Markdown

Before we progress further with our documentation, let us have crash course on MarkDown for Honkit.

Headings —

# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag

2. Emphasis —

*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

~~This text will be crossed out.~~

_You **can** combine them_

3. Lists —

* Item 1
* Item 2
  * Item 2a
  * Item 2b
1. Item 1
2. Item 2
3. Item 3
   * Item 3a
   * Item 3b

4. Links —

This is [an example](http://example.com/ "Title") inline link with a title.

[This link](http://example.net/) has no title attribute.

5. Tables —

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

6. Code —

Hello `this is inline code` world!

```
This is block of code
```

```java
public static void main(String[] args){}
```

7. Add Horizontal Line —

***
---

We have already covered images, this is all markdown we required to build our documentation. For more refer this.

What to include in documentation

Now let me walk through you about the contents that should be included in your documentation —

Introduction —

Make it neat, clear and straightforward. Introduction should first strong one liner as follows —

Then add an image of your tool, then more comprehensive paragraphs explaining features and highlights and what makes your tool unique. Then add quick links as follows —

Then elaborate on what your tool does, and provide feature.

What is the need for the tool

Highlight and provide proof for why we need this tool and how it is different from other tools.

Installation & Setup

Provide comprehensive guide on how to install & setup the tools with trouble shootings as well.

Usage Manual

Explain each and every functionality of the tool in detail with examples and scenarios.

Don’t forgot to include Images and Videos in this section.

Conclusion

Conclude with providing License, asking for contribution and providing contact details.

Hosting the Documentation

Run following command to build the documentation —

npx honkit build

It will generate a ‘_book’ directory.

This directory contains static website and all of the resources and pages. Navigate to this directory and run following command -

cd _book
python3 -m http.server 3000

And your documentation site will work smoothly. Transfer this site over github pages or netlify any other hosting service or you own and host it over their.

Conclusion

This is all we need to make an awesome documentation for our tool. Because without a documentation, reputation for tool is extremely hard to gain, plus people will loose interest in it due to unavailability of resources about the tool.

Found above post informative? Learned something new? Why not support me. Kindly support my work via ko-fi -> https://ko-fi.com/zinjacoder