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