t00m / kb4it Goto Github PK

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

Home Page: https://github.com/t00m/kb4it-adocs

License: GNU General Public License v3.0

Shell 0.20% Python 10.39% Smarty 4.15% CSS 58.59% HTML 0.02% JavaScript 26.64%

knowledge-base python3 static html website template asciidoctor metadata publishing-sharing wiki python uikit writing markdown markdown-to-html repository technical documentation static-site static-site-generator

kb4it's Introduction

About KB4IT

Introduction

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

You can see some demos here: https://github.com/t00m/kb4it-adocs

Motivations

The main aim is to provide an easy way to write my 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

Writing documentation: Documents must be in Asciidoctor format which is easy to learn.
Finding documents: Once a document is converted to html, properties can be browsed. Moreover, property pages have filters and a search entry to filter by title.
Publishing your repository: all necessary files are inside a directory. Browse it or copy it to your web server.
Serverless: There is no need for a web server. Of course, you can use one if you please.
Smart compiling: Only those documents added or modified are compiled.
Use the default themes or build your own custom theme
By modifying templates, it might be integrated with Github or Gitlab.

Cons

Not to much documentation at this moment
No online editor: At this moment, KB4IT doesn’t include any online editor. You must create or edit your documents with your preferred editor.
No dynamic search: KB4IT was developed to be as simple as possible.
No dependencies at all excepting Asciidoctor (as text processor and publishing toolchain) and Python (the programming language used).
API is not stable
Most of the requirements are tailored to my own necessities which might not be the same as yours.

Installation

From source

If you have used this app before, it might be necessary to uninstall it before:

pip3 uninstall kb4it -qy

Then, install it:

python3 setup.py install --user

Pypi package

pip3 install kb4it --user -U

Execution

The most typical usage would be:

$HOME/.local/bin/kb4it -source /path/to/asciidoctor/sources -target /path/to/target/directory -log DEBUG

If templates remain the same, force a new compilation:

$HOME/.local/bin/kb4it -source /path/to/asciidoctor/sources -target /path/to/target/directory --log DEBUG -force

If the directory containing the asciidoctor sources have a theme, it will be used. However, you can specify one:

$HOME/.local/bin/kb4it -source /path/to/asciidoctor/sources -target /path/to/target/directory -theme mytheme -log DEBUG

You can also specify any_datetime_attribute to sort your documents:

$HOME/.local/bin/kb4it -source /path/to/asciidoctor/sources -target /path/to/target/directory -sort Published -log DEBUG

Download

Get the code from Github: https://github.com/t00m/KB4IT

git clone https://github.com/t00m/KB4IT

Credits

Python Programming language that lets you work more quickly and integrate your systems more effectively.
Asciidoctor A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more.
UIKit A lightweight and modular front-end framework for developing fast and powerful web interfaces.
Geany Powerful, stable and lightweight programmer’s text editor that provides tons of useful features without bogging down your workflow. It runs on Linux, Windows and MacOS is translated into over 40 languages, and has built-in support for more than 50 programming languages.

Contact

Tomás Vírseda (aka t00m): [email protected]

I would appreciate to hear from your comments.

kb4it's People

Contributors

Stargazers

Watchers

kb4it's Issues

Pagination doesn't work properly

It repeats the number of pages to be displayed.

Finish Techdoc theme

Finish implementing all features for this theme

Events
Messages
Filtered key pages

Bookmarks

KB4IT should have a section or page for those document with the following property:

:Bookmark: True

Remove sources from an already cached directory leave some pages with inconsistencies

Detected a wrong behavior when sources files are moved/deleted from an (already cached) directory.

Affected property pages should be compiled again.

Workaround: delete cache directory.

Cache directory can be found by checking DEBUG output during the compilation.

Fix 1: redesign the algorithm to detect changes
Fix 2: add an optional parameter to force a new and clean compilation.

Improve templating

Current templating system is very basic (simple substitution).
By using mako template system, it is easier to create templates.

This adds the first dependency to the project. It was necessary.

Renaming documents doesn't force the compilation of the document.

Whenever the metadata or the body is changed, KB4IT detects the change and force a new compilation.

That doesn't happen when the title is changed. Fix it.

Do not show all doc cards when visiting pages with filters

Initially, when pages with filters are visited it shows all cards available in the database. That's is ok for a few doc cards. But not for many.

Check logging output

Verify that DEBUG, INFO, WARNING and ERROR messages are useful.

Demo returns 404

Your projects demo URL is a 404

t00m.github.io/KB4IT/demo

Allow custom index, about, and help pages.

Let people to use custom index, about and help pages instead of default ones.

Card icons missing

Until now, icons in cards depends on the availability of a value for the property 'Author'.

In future developments, KB4IT shouldn't have core properties.

Therefore, as proposal, KB4IT will look for an icon

if an icon is present for the author property
if not, it will look for an icon with the same name that the document in the resources/images/ directory
finally, if none is found, it will use the default generic icon.

Images path wrong

Images load on local but not in remote.
The images path should be relative. Now their path is absolute.

Show last added/modified documents

KB4IT should have a specific section or page for new documents added or modified.

Documentation needed

Explain workflow
Explain themes

Better HTML output

Clean and polish HTML output for a better understanding of the code

Create a demo

Create a demo site:

Add more tests and sources
Rename tests directory to demo-sources
Create target directory demo-output

Missing link to page 'All'

There is no link to page All with a list of all documents available in the knowledge database.

RSS Feeds

Allow users to keep track of new/modified documents in KB4IT:

One main feed for all documents in KB4IT
A feed for each property

Sort doc card list in pages with filters

Current filter output doesn't show cards list sorted by title.

Agnostic Knowledge Base

How to improve KB4IT so it doesn't depend on core properties (a predefined set of properties)?
Or should KB4IT look for a very small set of properties (like Author, Category, Scope)?

More command line options

Allow users to pass more command line options.

For example:

Force a new and clean compilation
Create a site only for a list of specific keys/values
etc...

OSError: [Errno 36] File name too long

After converting a json database of movies to KB4IT format and during the processing, I got the following error:

OSError: [Errno 36] File name too long: '/home/t00m/.kb4it/var/tmp/...

Theme techdoc

Create theme 'techdoc' (Technical documentation) with its own logic.

UI should be managed by themes

Till now, UIKit is included by default as the front-end framework for developing the web interface.
KB4IT shouldn't care about the framework used. Themes should provide it.

Pre/Post page hooks

Allow themes to insert code before and after the page content.

Themes

Allow KB4IT to use themes (user templates and scripts) to represent the information.

Eg.:

Technical documentation
Dictionaries
Notes
Bookmarking
Blog
Tasks

Keys with spaces doesn't work for modal windows

When a key with spaces is clicked to open the modal window, it doesn't work.

Improve compilation algorithm

Currently, because of a bug, the compilation algorithm compile again several documents even if it is not necessary.
Fix it!

Auto detect theme

It might be convenient to auto detect theme from a given source directory.

Templates

Create a set of standard templates (modifiable by users) with a set of predefined properties and values. This would make easy to add issues / tickets / reports / blog posts / etc...

Sources with spaces in their filename aren't handled properly

When a source filename has spaces, KB4IT is not able to handle it properly.

Blogging

By identifying a document with the property:

Category: Blog

KB4IT should handle it as a blog post.

Improve doc cards

Doc cards should display more info apart from title and author icon.

Display following metadata:
(=) Author
(=) Title
(+) Timestamp
(+) Category
(+) Scope
(?) Priority (badge)
(?) Status (change backround color)

Pagination

Enable pagination in order to display a large amount of values. Otherwise, it takes ages to display all doc cards at one.
Disable filters for key pages.