After many years without enough time to develop my beloved application based on Semantic MediaWiki, KB4IT, I decided that it was time to stop, forget it and take a sabatic year without thinking in develop anything at all.
Also, after moving abroad with my family to start a new position in a new company, it did that I rethink the priorities.
However, after discovering a project based on Asciidoctor from a fellow, I got really impressed how easy is to write documentation and export it to several formats. Few days later, I started a new application which, indeed, has come to replace this old project.
KB4IT helps you to write technical documentation in an easy way and build your own documentation repository.
How it works?
Given a source directory with asciidoc documents, the script read them, analyze the attributes (metadata), creates a temporary directory where they are processed, and finally, build the target directory with all sources converted to html in such way that it looks like a structured website with links to the home page, links to the attributes and values and many others sections (recent documents page, tagclouds, etc…)
In order to achieve this goal, a KB4IT document must have:
- A header (core and custom attributes)
- A body: the document itself following asciidoctor rules
- You can add as many attributes as you want
- You can change easily the stylesheet properties
- Asciidoctor sources is always linked to the output file so you can duplicate easily documents
- How much space requires plain text documents? Easy to backup/restore.
- Easy to find documents with a few key strokes
- Core properties are hardcoded in the script. They are based on my experience and in my needs. Therefore, if you are not very happy with them, the only solution is change the code. But, hey, it is Free Software, isn’t it? Anyway, I will try to find a solution.
- The html5 output is not very nice. During the pre-processing stage the script insert blocks of HTML code (for the top nav menu, for tag clouds, etc, …
- The scripts produce static code. It means that there are no search facilities
The scripts is still in an early stage of development. I have several ideas on mind but I don’t have too much time to develop them. So do not expect I release new versions often.
But any idea is welcome. Just send me an email with your thoughts.
Finally but no less important, the code is licensed under the terms o the GPLv3 so you are free to grab, extend, improve and fork the code as you want.