From cbebdf128bae6d5cb79c138d01ebd9ab67a937c3 Mon Sep 17 00:00:00 2001 From: njms Date: Tue, 29 Aug 2023 10:25:38 -0700 Subject: [PATCH] Add repo documentation --- LICENSE.md | 11 +++++++ README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 LICENSE.md create mode 100644 README.md diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..5ead2d1 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,11 @@ +This software is a gift. + +You may use it, you may explore its source code, you may extend it and you may hack it into some wildly new creation. It's yours now. But when you accept this gift, know that I offer it to you because I trust you, and with my trust comes a set of responsibilities. + +I give this gift to you for free out of love. I expect you will share it with others, and when you do, you will share it in the same spirit with which I share it with you. + +You will not use my gift to hurt people, any living creatures, or the planet. If you intend to use my gift to cause harm, then I am not giving this gift to you. + +When I give this gift for you, I'm inviting you to build a relationship with me. All software is a relationship, after all. I have made this gift for you, and in as much as you are able, you will help me make it better for all those with whom we share it. + +For more context on this "license," see [this article](https://njms.ca/posts/this-software-is-a-gift.html) diff --git a/README.md b/README.md new file mode 100644 index 0000000..9f2bf7a --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# 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.