blag/README.md

# 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>`

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 <SRC> <ALT>`

creates an image element with the given SRC (source) and ALT (alt text).  
no input.

#### `link <HREF>`

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
<h1>hello, world!</h1><p>the time is:
Mon Dec 16 22:42:00 +03 2024</p>
```

### arguments

blagposts rendered with the blag script will have arguments much like a regular
shellscript, except you should reference `$path` instead of `$0` when getting
the script path. `$0` is the path of blag itself.

## 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)
 - `RAW` (see [raw responses](#raw_responses))

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

### raw responses

if you set `RAW` to a non-empty value, bingus-blog will abort normal
function and instead respond with whatever your script outputted, setting
the Content-Type header to the value of `RAW`. this can be used to implement
APIs in blag (do not do this).

### cache invalidation

due to how blag works, the hash of the query params is stored alongside the
mtime of the post file. you can only tell bingus-blog "hey, don't cache me!"
from a post, but sometimes you need to invalidate the existing cache for all
query param combinations. to do that, `touch -c "$path"` from your post file.
this sets the mtime for the post to right now, invalidating the reference to
it as bingus-blog believes that the contents have changed.

### fastblag

:eyes:

## disclaimer

this is very bad and also pre-alpha quality software. dont come crying
to me when you get revshelled.