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 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:

header 1 <<< "hello, world!"

{
    echo "the time is:"
    date
} | paragraph

run blag on your post:

./blag post.sh > rendered.html

rendered.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)

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

👀

disclaimer

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