# calathea v1.0-beta

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: required string
data: optional anything
---
```

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](https://www.rust-lang.org/tools/install)

From there, run:

```
$ git clone https://codeberg.org/njms/calathea.git
$ cd calathea
$ cargo build --release
$ sudo cp target/release/calathea /usr/local/bin
$ 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](https://codeberg.org/njms/calathea), 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.html')
  -?,, -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.html`).


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.