How to create Documentation for your next hacking tool using Honkit GitBook! Step by Step Guide
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 init
to 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.
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
andnpm run serve
from 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 -
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
The Final Documentation shown above can be found here — https://net-square.com/browserbruter
Download the tool now — https://github.com/netsquare/BrowserBruter
If you found any mistake or have any suggestion kindly reach me at