### KB ###
`kb` is a simple knowledge base toolset built around a few key principles:
- Creating entries sholud be fast and require minimal mental effort.
- Entries sholud be short and explain small things whenever possible.
- Entries should be editable and have viewable history.
- Entries should be easily searchable.
- The core API server should be incredibly simple to setup and work with,
working simply with flat files and only requiring a small number of API
functions to use.
# HOW IT WORKS
The data directory contains a collection of json files. Each file name is the
same as the entry's ID. Thus, if a file with a given number doesn't exist, then
that entry doesn't exist. The API is used to interact with the data in an
efficient matter programatically, which should be used as a base for creating
tools and clients for working with the data - of which there are 2 reference
clients.
A user can create new entries quickly and with little effort to send them
straight into storage, and can search for entries to try and find required
information. Modifications can be made to entries to keep them relevant, and
more helpful entries can be boosted to make it easier for others to find
information. There isn't really any more to it.
`kb` is targeted mainly at small groups, such as those in an office that wish to
easily share information between them. As a result, it does not come with any
access control or accounts systems. It is however very feasible to write an
authentication proxy to sit in front of the API and use a customised client to
properly handle authentication. That is beyond the scope of the project though.
# API
You need but 7 simple requests to use `kb`:
GET /
List all entry IDs. Returns 'application/json':
{ ids : [ 0 , 1 , 7 ] }
GET /$n
Get the content of an entry. Returns 'application/json':
{
id : 123 , // unique numeric id of the entry
title : "The title" , // entry title
time : 12345678 , // unix timestamp for the entry
old : false , // boolean deprecation flag
tags : [ "some" , "helpful" , "tags" ] , // tags for searching
content : "large string body" ,
history : [
{
time : 12345678 ,
content : "old content"
}
]
}
If the entry doesn't exist, a 404 is returned.
DELETE /$n
Delete an entry. Here, the entire file is simply deleted. Returns 200 if
successful or 404 if the entry doesn't or no longer exists, making the
request idempotent.
POST /$n
POST /
Sends new entry content and tags. If just sent to `/api/e`, a new entry is
created and returns the ID of the newly created entry or a 500 if creating
the entry fails for whatever reason. If an entry ID is provided, the content
is sent as a modification to the given ID. `kb` keeps up to 16 items of
history (not including current version), so if that limit is reached, then
the oldest item of history is dropped. If the given entry ID does not exist,
then that entry is created and that same ID is returned on a success. The
payload of these requests should be 'application/json' and look like this:
{
title : "The title" , // property is updated
old : false , // property is updated
tags : [] , // property is updated
content : "blah" // used as new body
}
Only the body is required. Any other properties that are omitted are left
unchanged. If the new content is identical to the existing content (e.g. as
a result of a duplicate request), then no change is made and a 304 is
returned.
PATCH /$n
Modifies an existing entry. Intended to be used to apply small fixes such as
spelling corrections rather than providing any substantial new content. As a
result, this does not push the current content into history, but instead
overwrites it. The payload is of exactly the same format as the equivalent
POST request.
POST /s
Searches for entries given a string search term in the payload. Payload
should be 'application/json':
{ search : "my search term" }
Returns 'application/json':
{ results : [
{
id : 123 , // id of the result
relevance : 8 // calculated relevance (heuristic)
}
] }
The relevance is a heuristic value created by combining weighted values of
number of tag matches, content matches, and popularity. Higher is considered
better.
# CLI
A handful of commands make the CLI easy:
$ kb ls [-r]
Generates a formatted listing of all entries and opens them in $PAGER
(defaults to `less`). Sorts by ID, or `-r` can be provided to sort by
timestamp, with more recently created/modified entries at the top.
$ kb view ID
Opens a formatted view of the entry #ID in $PAGER.
$ kb new
Opens a formatted template in $EDITOR (defaults to `vim`) to fill in
information, then uses the resulting buffer to generate a new entry.
$ kb edit ID
Opens a formatted template in $EDITOR pre-populated with the content in
entry #ID for editing. An additional flag is present that allows specifying
whether this is a new version or just a patch/fixup.
$ kb rm ID
Deletes entry #ID
$ kb search TERMS...
Completes a search for entries based on the provided terms and displays
results in the same manner as `kb ls`.
The very first argument to `kb` should be the hostname/IP and port of the API
server. Users should create a shell alias to include this information
automatically. `kb` itself does not have a config file.
# WUI
The web UI is a SSR website frontend to the API server. It contains no
JavaScript at all. It can be configured to use a light or dark theme. The UI is
fairly self-explanatory.
### USAGE
Each project can be built by running `dub build` in the directories of each
project. Note that an internet connection is required for the build to succeed.
From there, you may simply put the resulting binaries somewhere in your system's
`$PATH`, optionally populate config files, and then just run them. The only
exception being the WUI which also requires copying the 3 CSS files to a
reasonable location (configurable in the WUI's options).
Note that the default data path for the API server is `./data`, which is
relative to the directory you are running the server from. Also, the default
static path for the WUI is `./static`, which is also relative. These should be
properly configured before using the programs.