zk uses the Handlebars template syntax for its templates. The list of variables available depends of the running command:
- Template context when creating notes (i.e.
zk new) - Template context when formatting a note (i.e.
zk list --format <template>)
Besides the default Handlebars helpers, zk ships with additional helpers which you might find useful. They are available to all templates.
The {{format-link}} helper renders an internal link to another note, according to the user preferences set in the note formats configuration.
{{format-link "path/to note.md" "An interesting note"}}
can generate (depending on the user config):
[An interesting note](path/to%20note.md)
[[path/to note]]
The second parameter title is optional.
There are a couple of template helpers operating on strings.
The {{concat s1 s2}} helper concatenates two strings together. For example {{concat '> ' 'A quote'}} produces > A quote.
- The
{{substring s index length}}helper extracts a portion of the given string. For example:{{substring 'A full quote' 2 4}}outputsfull{{substring 'A full quote' -5 5}outputsquote
You can get a date object from a natural human date (e.g. tomorrow, 2 weeks ago, 2022-03-24) using the {{date}} helper. It is most useful when paired with the {{format-date}} helper.
{{date "tomorrow"}}
{{format-date (date "last week") "timestamp"}}
The {{format-date}} helper formats the given date for display.
Template contexts usually provide a now variable which can be used to print the current date.
The default format output by {{format-date <variable>}} looks like 2009-11-17, but you can choose a different format by providing a second argument, e.g. {{format-date now "medium"}}.
| Format | Output | Notes |
|---|---|---|
short |
11/17/2009 | |
medium |
Nov 17, 2009 | |
long |
November 17, 2009 | |
full |
Tuesday, November 17, 2009 | |
year |
2009 | |
time |
20:34 | |
timestamp |
200911172034 | Useful for sortable filenames |
timestamp-unix |
1258490098 | Number of seconds since January 1, 1970 |
elapsed |
12 years ago | Time elapsed since then in human-friendly format |
If none of the provided formats suit you, you can use a custom format using strftime-style placeholders, e.g. {{format-date now "%m-%d-%Y"}}. See man strftime for a list of placeholders.
The {{slug}} helper generates a URL friendly version of a text. For example, {{slug "This will be slugified!"}} becomes this-will-be-slugified.
This is mostly useful to generate a safe filename containing the title passed to zk new --title "An interesting note". With the filename template {{slug title}}, it becomes an-interesting-note.md.
The {{prepend}} helper adds a prefix to every line of the given text or block. You can use it to generate a Markdown quote, for example:
{{prepend "> " "A quote"}}
{{#prepend "> "}}
A multiline
quote.
{{/prepend}}
The {{sh}} helper will call the given shell command and insert its output in the template. Your imagination is the limit!
Get today's events from your calendar:
{{sh "icalBuddy -b '* ' -nc eventsToday"}}
Insert a random quote:
{{prepend '> ' (sh 'fortune')}}
Download today's weather:
{{sh 'curl http://wttr.in/?0'}}
When used as a block helper, the block content will be passed to the command through a standard input pipe.
Will output "HELLO, WORLD!":
{{#sh "tr '[a-z]' '[A-Z]'"}}
Hello, world!
{{/sh}}
The {{style}} helper is mostly useful when formatting content for the command-line. See the styling rules for more information.
{{style 'red bold' 'A text'}}
{{#style 'underline'}}Another text{{/style}}
The {{json}} helper serializes its argument to a JSON value. This is useful to generate valid JSON objects, for example:
{ "title": {{json title}}, "tags": {{json tags}} }
->
{ "title": "A \"quoted\" title", "tags": ["example", "json"] }
Warning: The template parser trips on }}}, so make sure to add an extra space before the third }.
You can serialize the whole template context as a JSON object with {{json .}}, which is how zk list --format json produces its output.