Lists

Overview

TemplateMark provides powerful list iteration capabilities to render arrays of data. You can create both ordered and unordered lists, as well as format list items with localization support.

List Types

Unordered Lists

Create bulleted lists using the {{#ulist}} block:

{{#ulist arrayName}}
- {{this}}
{{/ulist}}

Ordered Lists

Create numbered lists using the {{#olist}} block:

{{#olist arrayName}}
- {{this}}
{{/olist}}

Basic List Example

{
  "$class": "[email protected]",
  "middleNames": ["Tenzin", "Isaac", "Mia"]
}

The `this` Keyword

Within a list block, {{this}} refers to the current item being iterated:

{{#ulist items}}
- {{this}}
{{/ulist}}

For simple arrays (strings, numbers), use {{this}} to access the value. For arrays of objects, access properties directly.

Iterating Object Arrays

When iterating over arrays of objects, access object properties directly:

Example with Object Array

{
  "$class": "[email protected]",
  "items": [
    {
      "name": "Widget",
      "quantity": 2,
      "price": 29.99
    },
    {
      "name": "Gadget",
      "quantity": 1,
      "price": 49.99
    }
  ]
}

Join Lists

The {{#join}} block formats arrays into natural language lists with localization support:

{{#join arrayName locale="LOCALE" style="STYLE" type="TYPE"}}{{/join}}

Join Parameters

locale

string

default:"en"

Language locale (e.g., en, en-GB, fr, de)

style

string

default:"long"

List style: long, short, or narrow

type

string

default:"conjunction"

List type: conjunction (and), disjunction (or), or unit

Join Examples

{
  "$class": "[email protected]",
  "items": ["CAR", "ACCESSORIES", "SPARE_PARTS"]
}

Localized Lists

Join supports multiple locales for international documents:

English (US)
English (UK)
French
German

{{#join items locale="en" style="long"}}{{/join}}

Output: CAR, ACCESSORIES, and SPARE_PARTS

{{#join items locale="en-GB" style="long"}}{{/join}}

Output: CAR, ACCESSORIES and SPARE_PARTS

{{#join items locale="fr" style="long"}}{{/join}}

Output: CAR, ACCESSORIES et SPARE_PARTS

{{#join items locale="de" style="long"}}{{/join}}

Output: CAR, ACCESSORIES und SPARE_PARTS

Complex List Patterns

Nested Lists

Create nested list structures:

{{#ulist categories}}
- **{{name}}**
  {{#ulist items}}
  - {{this}}
  {{/ulist}}
{{/ulist}}

Lists with Formulas

Combine lists with formula expressions:

{{#olist products}}
- {{name}}: {{% return (price * quantity).toFixed(2) %}}} {{currency}}
{{/olist}}

Conditional List Items

Use formulas for conditional rendering:

{{#ulist items}}
- {{name}} {{% return inStock ? '✓' : '✗' %}}
{{/ulist}}

Empty Lists

Handle empty arrays gracefully:

{{#clause items condition="return items && items.length > 0"}}
### Items
{{#ulist items}}
- {{this}}
{{/ulist}}
{{else}}
No items available.
{{/clause}}

List blocks render nothing if the array is empty. Use conditional clauses to show fallback content.

Advanced Examples

Shopping Cart

{
  "$class": "[email protected]",
  "items": [
    {"name": "Laptop", "quantity": 1, "price": 999.99},
    {"name": "Mouse", "quantity": 2, "price": 24.99},
    {"name": "Keyboard", "quantity": 1, "price": 79.99}
  ],
  "currency": "USD"
}

Attendee List

{
  "$class": "[email protected]",
  "attendees": [
    {"name": "Alice Johnson", "company": "Tech Corp"},
    {"name": "Bob Smith", "company": "Innovation Inc"},
    {"name": "Carol White", "company": "Future Labs"}
  ]
}

Best Practices

Choose the right list type

Use ordered lists for sequences, unordered for collections:

Steps (ordered):
{{#olist steps}}
- {{this}}
{{/olist}}

Features (unordered):
{{#ulist features}}
- {{this}}
{{/ulist}}

Use join for natural language

For prose, prefer join over lists:

Better: Available in {{#join sizes locale="en"}}{{/join}}
Output: Available in small, medium, and large

Avoid:
Available in:
{{#ulist sizes}}
- {{this}}
{{/ulist}}

Validate array existence

Check arrays exist before iteration:

{{#clause items condition="return items && items.length > 0"}}
{{#ulist items}}
- {{this}}
{{/ulist}}
{{/clause}}

Specify locale for join

Always set locale for consistent formatting:

{{#join items locale="en-GB" style="long"}}{{/join}}

Accessing parent contextUse ../ to access variables from the parent context within a list:

{{#ulist items}}
- {{name}}: {{price}} {{../currency}}
{{/ulist}}

List block syntaxList blocks require markdown list syntax (- or *) even though they generate numbered or bulleted lists:

Correct:
{{#olist items}}
- {{this}}
{{/olist}}

Incorrect:
{{#olist items}}
{{this}}
{{/olist}}

Variables

Access and format variables within lists

Conditionals

Add conditional logic to list rendering

Formulas

Use formulas for calculated list values

TemplateMark Syntax

Sample Templates

API Integration

Overview

List Types

Unordered Lists

Ordered Lists

Basic List Example

The `this` Keyword

Iterating Object Arrays

Example with Object Array

Join Lists

Join Parameters

Join Examples

Localized Lists

Complex List Patterns

Nested Lists

Lists with Formulas

Conditional List Items

Empty Lists

Advanced Examples

Shopping Cart

Attendee List

Best Practices

Variables

Conditionals

Formulas

Build docs developers (and LLMs) love

TemplateMark Syntax

Sample Templates

API Integration

​Overview

​List Types

​Unordered Lists

​Ordered Lists

​Basic List Example

​The this Keyword

​Iterating Object Arrays

​Example with Object Array

​Join Lists

​Join Parameters

​Join Examples

​Localized Lists

​Complex List Patterns

​Nested Lists

​Lists with Formulas

​Conditional List Items

​Empty Lists

​Advanced Examples

​Shopping Cart

​Attendee List

​Best Practices

​Related Topics

Variables

Conditionals

Formulas

Build docs developers (and LLMs) love

Overview

List Types

Unordered Lists

Ordered Lists

Basic List Example

The `this` Keyword

Iterating Object Arrays

Example with Object Array

Join Lists

Join Parameters

Join Examples

Localized Lists

Complex List Patterns

Nested Lists

Lists with Formulas

Conditional List Items

Empty Lists

Advanced Examples

Shopping Cart

Attendee List

Best Practices

Related Topics