-
Notifications
You must be signed in to change notification settings - Fork 0
Home
KB4IT is a static website generator based on Asciidoctor sources.
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.
-
The main aim is to provide an easy way to write technical documentation.
-
Don’t care about the formatting and focus in the task.
-
To allow teams to manage their own knowledge database.
-
Do not depend on third software products like word processors or complex web applications.
| Pros | Cons |
|---|---|
Easy to write technical documentation |
No online editor. |
Easy to find documentation |
There is no dynamic search. Search is based on static filters generated each time a page is compiled. |
Easy to publish documentation |
|
Easy to backup/restore documentation |
|
Serverless |
|
Smart compiling |
Documents must be in Asciidoc format which is easy to learn.
See help page for more details.
Take into account that, for each document, there is its corresponding Asciidoc source. So you can use it as a template to write another document without spend too much time.
There are many ways to find the document you are looking for.
Firstly, each document has properties which can you can browse. Eg.: If you remember the author of a document, just visit the author page.
Also, properties pages have filters. Moreover, there is a search entry to filter results by writin some of the letters of the title.
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.
However, you can upload/copy them to your own webserver.
There is no need for a web server. Of course, you can use one if you please.
However, KB4IT was designed to work in mixed environments where people uses shared folders (Eg.: Windows shares or directories mounted by NFS).
Only those documents added or modified are compiled. It reduces drasctically the amount of time and CPU needed to generate the website.
However, in order to achieve this, KB4IT uses a cache. If the cache is deleted or missing, the whole repository is compiled again.
A repository with 100 documents, in a Linux Virtual Machine with 2 CPU and 2G memory it takes less than 2 mins. Other test carried out in a server with more CPUs and memory, the compilation time is much less.
In order to speed up the compilation, KB4IT uses threading. By default, it launch 30 threads in parallel. So, please, be aware of this feature, as it will eat all CPU available until the compilation finishes.
At this moment, KB4IT doesn’t include any online editor. You must create or edit your documents with your preferred editor.
KB4IT was developed to be as simple as possible. No dependencies at all excepting Asciidoc (as text processor and publishing toolchain) and Python (the programming language used).
The main goal was to have something like a Wiki but just with plain HTML files in a directory. Nothing else. Because of this, no full text search can be implemented.
This is the flow:
-
Get source documents
-
Preprocess documents (get metadata)
-
Process documents in a temporary dir
-
Compile documents to html with asciidoc
-
Delete contents of target directory (if any)
-
Copy all resources (global and local) to target path
-
Copy all documents to target path
-
Copy source docs to target path
KB4IT is a set of Python 3 scripts.
The code is organized in the following way:
kb4it
├── resources
│ ├── offline
│ │ ├── docinfo
│ │ └── templates
│ └── online
│ ├── images
│ └── uikit
│ ├── css
│ ├── fonts
│ └── js
└── src
├── core
└── services
-
Offline resources: they are used to build target files (templates)
-
Online: resources to be copied to target directory
The most typical usage would be:
$HOME/.local/bin/kb4it -sp /path/to/source/docs -tp /var/www/html/repo --log INFO
Display help by passing -h as argument:
usage: kb4it [-h] -sp SOURCE_PATH [-tp TARGET_PATH] [-log LOGLEVEL]
[--version]
KB4IT by Tomás Vírseda
optional arguments:
-h, --help show this help message and exit
-sp SOURCE_PATH, --source-path SOURCE_PATH
Path for Asciidoc source files.
-tp TARGET_PATH, --target-path TARGET_PATH
Path for output files
-log LOGLEVEL, --log-level LOGLEVEL
Increase output verbosity
--version show program's version number and exit-sp is mandatory. KB4IT needs to know where your sources are.
-tp is optional. If this parametre is missing, a directory target will be created. If it exists, contents will be deleted.
-log accepts DEBUG, INFO, WARNING and ERROR
-
Target directory is created if it does not exist.
-
Source directory is never touched. Source documents are copied to a temporary directory
-
Contents on target directory are always deleted after compilation and replace it with those in the cache and the new ones compiled.
Get a copy from SVN repository:
svn checkout https://subversion.t00mlabs.net/kb4it/trunk kb4it