Handlematters

Self-contained template system with Handlebars and inline shell scripts

Introduction

Handlematters is a template system that combines Handlebars and shell scripts. It is intended to replace simple substitution tasks such as those done by envsubst.

Here is an example of a Handlematters template:

hello.hms

Any text before the context or template block is just a comment.
It will not be output.

--- context ---
greeting: echo hello

list: |
  for v in foo bar baz; do
    echo "* $v"
  done

--- template ---
{{greeting}}, world

{{list}}

Passing this file to handlematters will result in the following output:

$ handlematters hello.hms
hello, world

* foo
* bar
* baz

Let's take a closer look.

--- context ---
greeting: echo hello

list: |
  for v in foo bar baz; do
    echo "* $v"
  done

The context block is a YAML document. Each value of the property will be executed as a shell script and the output will be the resulting value.

--- template ---
{{greeting}}, world

{{list}}

The template block is a Handlebars template. {{...}} to output the context value. If you are not familiar with Handlebars syntax, have a look at https://handlebarsjs.com/.

Let's look at a more practical example:

Note: The expression in triplet braces {{{...}}} will be output without HTML escaping.

--- context ---
name: cargo metadata --format-version=1 --no-deps | jq -r .packages[0].name
author: cargo metadata --format-version=1 --no-deps | jq -r .packages[0].authors[0]

--- template ---
{{{name}}} by {{{author}}}

Will result in:

handlematters by Keita Urashima <[email protected]>

Of course, this README is also generated by Handlematters. See: https://github.com/ursm/handlematters/blob/main/README.md.hms

Usage

Self-contained template system with Handlebars and inline shell scripts

Usage: handlematters [FILE]

Arguments:
  [FILE]  Input file [default: stdin]

Options:
  -h, --help     Print help
  -V, --version  Print version