Hickey is a git-backed wiki written in Haskell using Pandoc-flavoured Markdown for pages, and supporting rendering plugins through external executables. Every single change, be it editing a page or uploading a file, is recorded as a separate commit - giving a clean and useful history, friendly to use with external tools.
Features:
-
Automatic linking of WikiWords.
-
[EmptyLinks]()link to the page of the same name. -
Highlight broken wiki links.
-
Inter-wiki links.
-
Call external plugins by using fenced code blocks.
-
Pages can have file attachments.
-
Automatically-updated category listings.
In addition, everything is done through git, the only configuration
external to that is the repo path: you can clone an entire wiki and
redeploy elsewhere with a regular git clone and starting a new
instance of Hickey.
Pandoc introduces a fenced code block syntax to Markdown, where you can specify the language (or other properties) of the code contained within, for example:
~~~~{.haskell}
main :: IO ()
main = putStrLn "Hello, world!"
~~~~
This will render with Haskell-specific syntax highlighting. However, by replacing "haskell" with the name of a plugin ("dot" is provided by default), then that plugin is executed.
Specifically, if a block has a single attribute, and the value of that attribute corresponds to the filename of something in the plugins/ directory of the repository, then that file is executed with the contents of the block as stdin, and the plugin emits Pandoc-flavoured Markdown on stdout.
This lets us write this:
~~~~{.dot}
graph graphname {
a [label="Foo"];
b [shape=box];
a -- b -- c [color=blue];
b -- d [style=dotted];
}
~~~~
…and get an image embedded into the page.
Plugin expansion is recursive, so plugins can generate code to be expanded by other plugins, but there is a depth limit of 100 to prevent infinite loops.
Wikis are all about linking things together and organising them, and Hickey provides some helpers to make common types of links easier for you.
All of these can be used both as a single word (delimited by spaces)
in the body text of an article, or in a link with an empty target,
e.g. [Foo]().
-
WikiWords: just use the page name to link to other articles on the wiki (caveat: in regular text the link must be CamelCased, to disambiguate from other words).
-
Page revision: use
pagename/revisionidto link to a specific revision of a page. -
Inter-wiki links: link to an external wiki, configured in interwiki.conf, with
prefix:pagename. -
Raw URLs: literal URLS, starting with "http://", "https://", or "ftp://", are turned into links automatically.
Categories allow you to group related pages together, and in Hickey this is achieved by using Pandoc's YAML front-matter. Simply start your document with something like:
---
category: Foo
---
…and your page will show up in a list on the article CategoryFoo. You can specify multiple categories, using the "categories" field, and categories can be in a YAML list, or simply separated by spaces with (optional) commas.
Hickey doesn't have user accounts, store the IP of editors, or even force people to use a consistent handle when saving changes. Thus, if you want to expose your Hickey-powered wiki to a network not under your control (whether that's a good idea or not is a whole different kettle of fish), you can make articles read-only by adding their name (one per line) to the file "locked.conf" in the repository root.
You can also lock all articles by adding "*" to the file.
The examples/ directory includes a sample configuration file, which simply specifies the path to the repository (which can be absolute or relative to Hickey's working directory) and a sample wiki structure.
You can get started by just copying the contents of the sample wiki to a git repository and committing them.
Hickey uses git for everything, including static files. If you're having difficulty accessing something, make sure you committed it, and didn't simply place it in the directory structure.
Haddock documentation generated from the code, in a reasonably up-to-date format, can be accessed here.