139 lines
3.3 KiB
Markdown
139 lines
3.3 KiB
Markdown
# 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>
|
|
```
|
|
|
|
## 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.
|