95 lines
2.9 KiB
Markdown
95 lines
2.9 KiB
Markdown
# 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.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.
|