Template syntax quick start

Markdown

The main template is evaluated as Markdown. Markdown helps you to add structure and formatting with minimal markup. As Markdown also supports HTML blocks you can always use HTML when Markdown syntax is not enough.

Internally Bravo Notes use the same markdown parser as Azure DevOps does. This means that apart from some extras you can expect the same behavior that is well documented in the Azure DevOps docs over here.

Handlebars templating

On top of Markdown and HTML Handlebars syntax is used to enable looping over work items and outputting work item fields.

Handlebars uses {{ curly braces }} to bring data and logic into your template (they look like handlebars..get it?).

If you are comfortable with some more technical details we recommend you learn a few of the basics on the Handlebars website. We try to give you all the info you need in these docs.

Outputting HTML in handlebars helpers

When outputting work item content from rich text (HTML) fields or when importing HTML content via the import or partial helpers be aware that by default Handlebars will return escaped HTML.

This means in the final document you may expect to see some text rendered as a second level heading but you get a <h2>My heading</h2> in the document.

To fix this instead of double curly braces {{ }} be sure to use tripple curly braces {{{ }}}.

Examples

List all work items

{{#workItems}}
- {{id}} - {{title}}
{{/workItems}}

List work items that have the specified label.

{{#workItems 'bugfix'}}
- {{id}} - {{title}}
{{/workItems}}

List work items that have all of the specified labels.

{{#workItems 'user-management' 'bugfix'}}
- {{id}} - {{title}}
{{/workItems}}

Optional section of filtered work items

{{#section '$UserStory'}}

# Just User Stories

{{#workItems}}
 - {{ field 'Title' }}
{{/workItems}}

{{/section}}

Optional section of filtered work items with fallback content

{{#section '$Bug'}}

# Known issues in this release

{{#workItems}}
 - {{ field 'Title' }}
{{/workItems}}
{{else}}
-- no bugs in this release: yay! -
{{/section}}

Output work item content from any field. Please notice the tripple curly braces {{{ }}}.

{{#workItems}}
- {{field 'Title'}}
{{/workItems}}

For standard fields, you don't have to use the fully qualified field name

{{#workItems}}
- {{{field 'Title'}}} 
{{/workItems}}

Use tripple curly braces {{{   }}} when outputting HTML fields like Description.

{{#workItems}}
- {{{field 'Description'}}}
{{/workItems}}

Output image attachments

{{#images}}
### {{title}} - {{comment}}
![{{title}} - {{comment}}]({{{url}}})
{{/images}}

Sort list of work items by any field ascending or descending

{{#workItems orderBy='Priority'}}
- {{{field 'Title'}}
{{/workItems}}

{{#workItems orderByDescending='Effort'}}
- {{{field 'Title'}}
{{/workItems}}

Output linked work items

{{#workItems}}

## {{{field 'Title'}}}

{{#links 'Microsoft.VSTS.Common.TestedBy-Forward' }}
- Tested by: {{{field 'Title'}}}
{{/links}}

{{/workItems}}

Output linked work items as an optional section

{{#workItems}}

## {{{field 'Title'}}}

{{#linkSection 'Microsoft.VSTS.Common.TestedBy-Forward' }}

### Tested by

{{#workItems}}
- {{{field 'Title'}}}
{{/workItems}}

{{/linkSection}}

{{/workItems}}

Output linked work items as an optional section with fallback content

{{#workItems}}

## {{{field 'Title'}}}

{{#linkSection 'Microsoft.VSTS.Common.TestedBy-Forward' }}

### Tested by

{{#workItems}}
- {{{field 'Title'}}}
{{/workItems}}

{{else}}

CAUTION: No tests found for this work item!

{{/linkSection}}

{{/workItems}}

Let us know if you miss anything. Happy to help!