Skip to content

Templates and metadata

Brett Terpstra edited this page Aug 7, 2022 · 3 revisions

You can create templates to reuse topics in multiple build note files. Create files using the same formatting as a build note in ~/.config/howzit/templates with .md extensions. Name them the way you'll reference them:

~/.config/howzit/templates
- markdown.md
- ruby.md
- obj-c.md

Use howzit --templates for a list of templates you've created, along with the topics they'll add when included. Just in case you make a bunch and can't remember what they're called or what they do. I was just planning ahead.

You can then include the topics from a template in any build note file using a template: key at the top of the file.

Howzit allows MultiMarkdown-style metadata at the top of a build notes file. These are key/value pairs separated by a colon:

template: markdown
key 1: value 1
key 2: value 2

The template key can include multiple template names separated by commas.

Additional metadata keys populate variables you can then use inside of your templates (and build notes), using [%key]. You can define a default value for a placeholder with [%key:default].

For example, in the template markdown.md you could have:

### Spellcheck

Check spelling of all Markdown files in git repo.

```run
#!/bin/bash
for dir in [%dirs:.]; do
    cd "$dir"
    /Users/ttscoff/scripts/spellcheck.bash
    cd -
done
```

Then, in a buildnotes.md file in your project, you could include at the top of the file:

template: markdown
dirs: . docs

# My Project...

Require metadata

You can define what metadata keys are required for the template using a required: key at the top of the template. For example, if the template script.md uses a placeholder [%executable] that can't have a default value as it's specific to each project, you can add:

required: executable 

at the top of project.md. If the template is included in a build notes file and the executable: key is not defined, an error will be shown.

Use commas to separate multiple required keys

Include a subset of topics

If you only want to include certain topics from a template file, use the format template_name[topic] or include multiple topics separated by pipes: template_name[topic 1 | topic 2]. You can also use * as a wildcard, where template_name[build*] would include topics "Build" and "Build and Run".

If a topic in the current project's build note has an identical name to a template topic, the local topic takes precedence. This allows you to include a template but modify just a part of it by duplicating the topic title. When viewing your build notes, topics included from templates are prefixed with the template name. You do not need to include the prefix to override a topic.

Nest templates

Templates can include other templates with a template: key at the top of the template.

Clone this wiki locally