diff --git a/README.md b/README.md new file mode 100644 index 0000000..035dac2 --- /dev/null +++ b/README.md @@ -0,0 +1,139 @@ +# blag + +blogging in bash + +all blag really is can be summed up as 'a collection of functions for +writing markup in bash, alongside +[bingus-blog](https://git.slonk.ing/slonk/bingus-blog) integration', +but that would be doing it injustice. blag is not just a shellscript. +blag is a way of life- no, blag is the _meaning_ of life. +keep on blagging. + +## how to blag + +first create a file for your blagpost. the name doesn't matter, but i like to +end mine with `.sh` (this is a requirement for bingus-blog integration). + +then, render it with blag: `./blag my_epic_post.sh > rendered.html`. +you'll notice that the resulting html is blank. this is because the post you +wrote did not output anything. in blag, we use the inbuild functions (or plain +printf if you're in a pinch) to actually compose our markup. see below for more +information on those. + +### functions + +functions in blag generally take html from stdin and output html. this makes it +possible to form complex pipes merging and transforming the content, similar to +applicative programming. an example of this composability: +`curl wttr.in/?2n | escape | codeblock`. + +#### `escape` + +html-escapes text from stdin. + +#### `header ` + +LEVEL is a number from 1 to 5, representing h1 to h5. +creates a header from stdin. + +#### `paragraph` + +creates a paragraph from stdin. simple enough. + +#### `image ` + +creates an image element with the given SRC (source) and ALT (alt text). +no input. + +#### `link ` + +formats stdin as a link to HREF. + +#### `br` + +outputs a line break. +no input. + +#### `br_lines` + +replaces line feed characters from stdin with html line breaks. + +#### `codeblock` + +creates a codeblock from stdin. + +### sourcing blag from posts + +the regular blag workflow has you running the `blag` binary with the +path to your post, but you could very well just source `blag` _from the post_. +doing so will expose the blag functions to your shellscript but not trigger +blag's cli. + +### example + +`post.sh`: + +```sh +header 1 <<< "hello, world!" + +{ + echo "the time is:" + date +} | paragraph +``` + +run `blag` on your post: + +```sh +./blag post.sh > rendered.html +``` + +`rendered.html`: + +```html +

hello, world!

the time is: +Mon Dec 16 22:42:00 +03 2024

+``` + +## bingus-blog integration + +set `engine = "blag"` in your configuration file. the naming format is +"(post name).sh" on disk, just like default markdown posts. + +the first line your blag outputs MUST be the post metadata. you MUST set the +following variables in your blag: + + - `TITLE` + - `DESCRIPTION` + +you SHOULD set `AUTHOR`, though it does default to the name of the user running +`blag`. + +you MAY set these variables: + + - `ICON` + - `ICON_ALT` + - `COLOR` + - `TAGS` (as an array!) + - `DONT_CACHE` (to explicitly not cache the rendered blag) + - `WRITTEN_AT` (if the filesystem/libc doesn't support it) + +you SHOULD NOT set `MODIFIED_AT` unless you have a valid reason. + +after setting all the variables call the `metadata` function before outputting +anything else. + +the environment variable `BLAG_QUERY` is provided to you as the unmatched +query parameters for the request that invoked the rendering, in json. you can +safely use `jq` to parse it. + +the rest is normal + +### fastblag + +:eyes: + +## disclaimer + +this is very bad and also pre-alpha quality software. dont come crying +to me when you get revshelled. diff --git a/blag b/blag index a229d19..684fd02 100755 --- a/blag +++ b/blag @@ -1,13 +1,8 @@ #!/usr/bin/env bash #shellcheck disable=SC2155 -print_help() { - echo "Usage: $0