rakosh

rakosh is a place to store "nuggets" of information. Like a knowledge base, but based on small nuggets rather than pages.

Intro

raskosh is offline-first, for now -- this is a prototype. Data are stored in an ArangoDB database. In future there may be a server and a frontend. For now, there is a tool for depositing data into ArangoDB, and one for extracting it as a Gatsby site.

One aim of this prototype is to develop an ontology for these "nuggets" of information and the relationships between them.

Usage

In this first iteration, the use of ArangoDB is a sledgehammer to crack a site-generation nut. In future, it will be nice to see additional extraction targets and an online mode with an API; and even a frontend. For now, ArangoDB is acting as a schema validation tool effectively.

ArangoDB can be installed in various ways. Since the ArangoDB instance need not be long lived, using a Docker container is probably the simplest. To run a container, use this command:

    docker run -e ARANGO_NO_AUTH=1 -p 8529:8529 --rm \
        arangodb/arangodb arangod --server.endpoint tcp://0.0.0.0:8529

Include a --volume to persist the data if required.

Once the server is up, content laid out in a specific* directory structure can be deposited like so:

    rakosh deposit ../my/content/dir

TODO

BUG: slug lookup sometimes lists secondary slug first
reduce how much is rendered in non-main nuggets
BUG: apostrophe in label
better styling of content in gatsby, e.g. blockquote
better PDF styling, including title at top
buttons for breadcrumb & metadata, plus persistence of button state
better search results presentation
CLI command to simplify creation of new FS nuggets
search box usage hints
finalize initial docs
"tags" for search (plus author)
dark mode
support <link> links in markdown?

Terminology

Term	ArangoDB Objects	Description
mine	Database	the content store
nugget	Document, Vertex	a small piece of useful information
~~lode~~	~~Vertex~~	~~a top-level content category~~ (Not used)
seam	Vertices	a set of nuggets that exist at the same level in the mine
passage	Vertex	non-content verticies used to link content together
~~vein~~	~~Vertices, Edges~~	~~a route through the mine that defines a nugget's location~~ (Not used)
primary	Graph	internal - defines the relationship between all other objects
edges	Edges	internal - name of the collection use for all edges

Concepts

Command Line Interface

The Command Line Interface program is called rakosh.