Output Template Guide

Basic information

The templates are in jinja2 form.

Exposed fields

class scrummd.formatter.TemplateFields(config: ScrumConfig, card: Card, cards: Collection, interactive: bool, groups: list[tuple[FIELD_GROUP_TYPE, list[str]]], meta: dict[str, FieldMetadata])

Bases: object

Fields to pass to the template

card: Card

The card being formatted.

cards: Collection

The full collection of cards.

config: ScrumConfig

The relevant ScrumMD config.

groups: list[tuple[FIELD_GROUP_TYPE, list[str]]]

Ordered keys groups by their block type in the md file.

interactive: bool

Whether the command is being run in an interactive terminal.

meta: dict[str, FieldMetadata]

Metadata from the fields of original source md.

Replaceable macros

Purpose

Replaceable macros offer hooks into some particular functionality to provide more control over formatting. They must be define with exactly the parameters listed here to function.

card_ref

Description

Used to format any card references inside a field.

Parameters

component

The scrummd.source_md.CardComponent that is being expanded. The card will be none if the card is not found.

Default

[[ {{ component.card_index }} ]]

Setting as default

default_<program>.j2

Each program searches:

  • the current working directory;

  • the .templates directory in the scrum_path

  • the templates directory in the scrum_path

  • templates in the scrummd package;

for default_<program>.j2. For instance, if you add a file called default_scard.j2 to <scrum_path>/templates, it will overwrite the default template.

In Configuration

Configuration overrides the implicit default_<program>.j2 templates.

Define the scard default template with default_template.

Example template

 1{%- if interactive -%}
 2    {%- set HEADER = "\x1b[31m" -%}
 3    {%- set TITLE = "\x1b[36m" -%}
 4    {%- set RESET = "\x1b[0m" -%}
 5    {%- set BOLD = "\x1b[1m" -%}
 6    {%- set MISSING = "\x1b[31;1m" -%}
 7    {%- set DIM = "\x1b[38;5;237m" -%} {# 256 color term - most should be good, the rest will ignore #}
 8    {%- set BRIGHT = "\x1b[1m" -%}
 9{%- else -%}
10    {%- set HEADER = "" -%}
11    {%- set TITLE = "" -%}
12    {%- set RESET = "" -%}
13    {%- set BOLD = "" -%}
14    {%- set RED = "" -%}
15    {%- set DIM = "" -%}
16    {%- set BRIGHT = "" -%}
17{%- endif -%}
18{%- macro card_ref(component) -%}
19    {%- if component.card is not none -%}
20        {{ BOLD }}[[{{ component.card_index }}]]{{ RESET }}
21    {%- else -%}
22        {{ MISSING }}[[{{ component.card_index }} - MISSING]]{{ RESET }}
23    {%- endif -%}
24{%- endmacro -%}
25{%- macro code_block(component) -%}
26{{ DIM }}```{{ RESET }}{{ BRIGHT }}{{component.value}}{{ RESET }}{{ DIM }}```{{ RESET }}
27{%- endmacro -%}
28{%- macro code_quote(component) -%}
29{{ DIM }}`{{ RESET }}{{ BRIGHT }}{{component.value}}{{ RESET }}{{ DIM }}`{{ RESET }}
30{%- endmacro -%}
31---
32{{ TITLE }}{{ card.index }}: {{ card.summary }}{{ RESET }}
33---
34{% for key, value in card.udf.items() -%}
35    {% if value is none -%}
36    {% elif value is string -%}
37        {% if "\n" in value %}
38{{ HEADER }}# {{ key }}{{ RESET }}
39
40{{ value | apply_field_macros() }}
41        {%- else %}
42{{ HEADER }}{{ key }}{{ RESET }}: {{ value | apply_field_macros() }}
43        {%- endif -%}
44    {%- elif value is number -%}
45{{ HEADER }}{{ key }}{{ RESET }}: {{ "%.2f"|format(value) }}
46    {%- elif value is iterable %}
47{{ HEADER }}# {{ key }}{{ RESET }}
48        {% for item in value %}
49  - {{ item -}}
50        {% endfor %}
51    {% endif %}
52{% endfor %}