KB4IT

Introduction

KB4IT is a static website generator based on Asciidoctor sources mainly for technical documentation purposes.

KB4IT stands for Knowledge Base for IT.

Taking advantage of the user-defined attributes feature in Asciidoctor, KB4IT can parse Asciidoctor sources, extract all metadata available and create something similar to a wiki. In this way, all information provided by the user can be easily related.

Please, note that the application is still under development. However, I use it in my day to day for my own documentation repository.

I'd be very grateful if you could test it and tell me your opinion.

Demo

Before continue reading the details, you might take a look to a demo to have an idea of what is this project all about.

Motivations

The main aim is to provide an easy way to write technical documentation.

• Don’t care about the formatting and focus on the contents.
• To allow teams to manage their knowledge database easily.
• Do not depend on third software products like word processors or complex web applications.

Features

Pros

• Easy to write technical documentation

Documents must be in Asciidoctor format which is easy to learn.

For each document published, there is its corresponding Asciidoctor source. So you can use it as a template to write another document without spending too much time.

• Easy to find documentation

Each document has properties which can be browsed. These property pages use filters.

Moreover, there is a search entry to filter results by writing some of the letters of the title.

• Easy to publish documentation

All documents you write are compiled/converted to HTML files.

Just put them in any folder and point your browser to:

/target/path/index.html
c:\target\path\index.html

However, you can upload/copy them to your own web server.

• Easy to backup/restore documentation

Just backup your sources directory and restore them in another PC or server. Use the KB4IT application to compile them again.

Of course, you can backup the target directory with all the html files and resources and it will work anywhere.

• Serverless

There is no need for a web server. Of course, you can use one if you please.

KB4IT was designed to work in mixed environments where people use shared folders (Eg.: Windows shares or directories mounted by NFS).

• Smart compiling

Only those documents added or modified are compiled. It reduces drastically the amount of time and CPU needed to generate the website.

To achieve this, KB4IT uses a cache. If the cache is deleted or missing, the whole repository is compiled again.

To speed up the compilation, KB4IT uses threading. By default, it launches 30 threads in parallel. So, please, be aware of this feature, as it will eat all CPU available until the compilation finishes.

Cons

• No online editor.
• There is no dynamic search (search is based on static filters generated each time a page is compiled).
• KB4IT doesn't work on Windows due a limitation with the length of parameters passed (sad but true)

Dependencies

• Python
• Asciidoctor
• UIKit (bundled with KB4IT)

License

The code is licensed under the terms of the GPL v3 so you're free to grab, extend, improve and fork the code as you want.

Download

You can donwload the source code in GitHub: