calathea

Tags: projects

calathea is a small program used to generate static wikis. It takes a directory of cmark plus github flavoured markdown pages with [[wikilinks]] and renders them to HTML. The output is a flat directory of HTML pages where the wikilinks are converted to relative links.

This project is a complete rewrite and backwards-incompatible version of my other project, now known as ccalathea, which was a simpler version of this written in C.

features

Rendering wikilinks
Ability to keep track of incoming links
Named wikilinks (i.e. [[link title|actual page]])
Templating with Liquid
YAML frontmatter for specifying extra data to go with your page

Complete, valid yaml frontmatter for a page:

---
title: required string
permalink: optional string
data: optional anything
---

If a permalink is not specified, then the resultant file will have the file stem of the source file and the extension html.

Besides the above, the following variables can be accessed from the global scope in the template:

incoming - a list of objects in the form of { title, permalink, data, id } that link to this page
id - a trimmed, lower-cased version of the current page's title used internally to reference pages

installation

calathea has only been tested on Linux, but it should run on most unix systems and macOS as is. It may run on Windows as well, but I don't have a Windows machine to try it out.

From source

Installing from source requires Cargo, which you can install by visiting the Rust website

From there, run:

$ git clone https://codeberg.org/njms/calathea.git
$ cd calathea
$ cargo build --release
$ sudo cp target/release/calathea /usr/local/bin
$ sudo chmod +x /usr/local/bin/calathea

If you don't have Git and don't want to set it up, you can also go to the repo on Codeberg, click on the three dots under the bar listing the number of commits, branches and tags, and download it as an archive.

To uninstall,

$ sudo rm /usr/local/bin/calathea

usage

To see a list of options, run:

$ calathea --help

Usage: calathea [OPTION...]

  -o, --output=dir           Output directory (default: './build')
  -s, --src=dir              Source directory of pages (default: './pages')
  -t, --template=file        Template file path (default: './template.liquid')
  -?,, -h, --help            Give this help list
  -v, --version              Print the version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

Running calathea builds pages (by default, any filies in ./pages) to HTML files outputted in the specified output directory (by default, ./build). To do this, it renders the pages and inserts them into your template file (by default, ./template.liquid).

You can specify information about the page in the "frontmatter" in YAML-format, like so

---
title: Page Title
permalink: my-page-permalink.html
---

Here is some page content

Only the title is mandatory.