WeeWiki

WeeWiki

A weewiki page about weewiki!

Description

Weewiki is a tiny scriptable wiki engine designed to build personal mind maps. It is used to power this personal wiki.

The core engine is written in C via the Worgle literate programming environment.

Wiki pages are primarly stored inside of a SQLite database, and are written using org syntax (presumably via org-mode and emacs). The org parsing is done via a custom parser, written in C.

On top of the core engine is a scripting environment. For this, the Janet language is used. Janet code can be run inside of a wiki page, and can be used to dynamically generate org content, which is then turned into HTML by the parser. This can be used to do things like create dynamic reference links, such as this one!

WeeWiki On SourceHut

WeeWiki source coded is maintained using Fossil, but has been exported to a read-only git repository for convenience.

The repository in question can be found at sourcehut: https://git.sr.ht/~pbatch/weewiki.

Usage

Creating a page

This can be done weewiki add foo, where foo is the name of your page.

Editing a page

To edit a page, run weewiki edit foo. This will create a page called foo and open it up inside of the text editor set by EDITOR.

Deleting a page

Should be wiki del foo, where foo is the name of the page.

Linking Pages

Oftentimes it is easier to have a wiki page be externally tracked, rather than tracked internally inside of a sqlite database.

An existing internal file can be linked to external file using the command weewiki link foo foo.org where foo, is the name of the page, and foo.org is the name of the file to be created. If an external file has already been created and edited, use the -f flag to force things like so: weewiki link -f foo foo.org.

Once a file is linked, a page can be edited via the external file, rather than calling weewiki edit. Calling weewiki sync will update the wiki page.

Syncing Pages

Page syncing is a way to edit and manage pages externally.

An (existing) page can be linked with weewiki link foo foo.org.

Now, the page can be externally edited and tracked.

Any new changes in the pages of the wiki can be synchronized with:

weewiki sync

Synchronization works by comparing the modification time of the external file with the one stored in the link table, and will choose the newest to overwrite the entry in the database and the external file. Keep in mind that this is a simple overwrite with no fancy merging.

Dumping The Wiki

The entirety of a weewiki can be dumped to a janet script using the command weewiki dump foo.janet where foo.janet is the name of the file to write to. Omitting this causes the file to be written to stdout.

The generated janet script can be used to reconstruct the wiki database. This can be done using the command weewiki janet foo.janet.

The exported dump file will not include content for linked files, only the file links. It is expected that external files be present.

Dump files are useful for reconstructing a wiki database on another computer. The script is text based, which makes it suitable for tracking via an SCM like git or fossil.

A sample config file

Here is the config file used by this weewiki page:

(def ww-dir "_site/wiki")
(def webroot "/wiki")

(defn ref (link name)
  (org
   (string
    "[["
    (string webroot "/" link)
    "]["
    name
    "]]")))

(defn html-header
  []
(print
``<!DOCTYPE html>
<html lang="en">
<head>

<meta charset="utf-8">
<link rel="stylesheet" href="/css/style.css">

</head>
<body>
<div id="main">
``)
)

(defn html-footer
  []
  (print
``
</div>
</body>
</html>
``
))

A sample makefile

Based off the one used for this wiki:

default: export

export: db
	$(RM) -r _site/wiki
	mkdir -p _site/wiki
	weewiki sync
	weewiki export
	mv mkdb.janet mkdb.janet.old
	weewiki dump mkdb.janet

db:
	cmp mkdb.janet mkdb.janet.old ||\
		weewiki janet mkdb.janet

dump:
	weewiki dump mkdb.janet

transfer:
	mkdir -p _live/wiki
	cp -r _site/wiki/* _live/wiki

Running "make" will automatically export all the pages to a folder called _site/wiki. equivalent to "make export".

"make dump" will create a wiki dump, which can then be used to reconstruct the database. The wiki dump is stored as a janet file mkdb.janet.

"make db" will regenerate the database.

database generation and dumping happens automatically when exporting/transfering files.

Setting/Getting values

A page value FOO can be retrieved directly using the command:

weewiki get FOO

A page value FOO can be set directly from the commandline using the command

weewiki set FOO "one two three"

Pages that start with '@' are ignored when the wiki is exported. They can be used as a sort of key/value storage.

weewiki set @VERSION 1.01
weewiki get # returns 1.01

WeeWiki Server

If enabled, a small http server can be spawned to dynamically generate wiki pages. This is NOT meant for production.

The command:

weewiki server

Will spawn a http server on port 8080 by default.

Pages can be retrieved under the /wiki. The page "foo" can be accessed via "http://localhost:8080/wiki/foo".

Other Notable Wikis

The monolith program uses two weewiki instances. One is the main wiki, and the other is the program wiki, which is automatically generated from portions written in worgle and worgmap.

The sndkit project manages literate programs inside of a weewiki.