Template Directives

Directives use :::name ... ::: syntax to mark semantic regions of your template (similar to fenced code blocks in Markdown). Each directive compiles to the appropriate structure for each channel.

Norq has 17 directives: 14 content directives, 2 control flow directives, and :::table for iterable data tables.

Directive parameters

Content directives accept optional {key="value"} attributes on the opening line. Each directive documents the attributes it honours and which channels apply them — most are email-only but some are read by other channels (e.g. :::media {type="video"} is read by the Slack compiler). Expressions like {{var}} are supported in values.

Universal attributes

All directives support:

bg and color resolve in two tiers: literal #hex first, then any token name defined in brand.tokens.colors (so bg="secondary" resolves to brand.tokens.colors.secondary if you’ve defined it). Values that match neither tier fail with template/unknown-bg-token / template/unknown-color-token at lint time (Error severity) — typos can’t silently pass through.

Editor metadata attributes ($-prefixed)

Attribute keys starting with $ are reserved for editor and tooling metadata. They are preserved on disk (parser + norq fmt round-trip them byte-exact) but ignored by every channel compiler — they never appear in rendered output.

Unregistered $-prefixed attributes (e.g., $customTag="v1") are silently accepted by the linter so editors and vendor tooling can store arbitrary metadata without a spec PR. Vendor-specific metadata should be further namespaced ($suprsend-*, $maily-*).

::: section {$editable-by="admin"}
  Legal footer — edited by compliance team only.
:::

Placing a registered block-only attribute (like $editable-by) on an inline element fires editor/metadata-wrong-context:

<!-- ❌ $editable-by is not valid on inline links -->
See [our docs](https://example.com){$editable-by="admin"}.
 
<!-- ✅ Lock the surrounding block instead -->
::: section {$editable-by="admin"}
  See [our docs](https://example.com).
:::

Directive-only attributes

Examples:

::: header {bg="#1e3a5f" color="#ffffff" align="center"}
White text on dark header
:::
 
::: callout {bg="#fff3cd" color="#856d0e"}
Warning-styled callout
:::
 
::: footer {align="right" color="#999999"}
[Unsubscribe]({{unsubscribe_url}})
:::
 
::: hero {url="{{hero_image_url}}"}
# Dynamic background image
:::

Content directives

:::header

Top section of the notification – logos, brand name, title.

::: header
Order Shipped
:::

:::footer

Bottom section – legal text, unsubscribe links, context.

::: footer
[Unsubscribe]({{unsubscribe_url}})
:::

:::table

Iterable data table — combines table rendering with array iteration. Header row renders once, template row repeats per item. Supports variable pipe arguments in cells.

::: table products as item
| Product | Qty | Subtotal |
|---------|-----|----------|
| {{item.name}} | {{item.qty}} | {{item.cost | multiply item.qty | currency "USD"}} |
:::

If the collection is empty, only the header row renders (empty table). The | inside {{ }} expressions is handled correctly — it won’t break column separation.

:::action

CTA buttons. Contains Markdown links with style hints.

::: action
[Track Order]({{tracking_url}}){primary}
[Cancel Order]({{cancel_url}}){danger}
[View Details]({{details_url}}){secondary}
:::

Button styles: {primary}, {secondary}, {danger}, {success}, {warning}.

:::callout

Highlighted note or warning box.

::: callout
Your payment method will be charged within 24 hours.
:::

:::hero

Full-width hero image.

::: hero
![Hero banner](https://cdn.example.com/hero.png)
:::

:::fields

Key-value pairs, one per line. Useful for order details, invoice line items, etc.

::: fields
Order ID: {{order.id}}
Status: {{order.status}}
Total: {{order.total}}
:::

:::media

Embedded image, video, or file. Use the type parameter to specify the media type.

::: media type=image
![Product photo](https://cdn.example.com/product.jpg)
:::
 
::: media type=video
[Watch the demo](https://cdn.example.com/demo.mp4)
:::

Params: type=image (default), type=video, type=file.

:::columns

Multi-column layout with nested :::col blocks.

::: columns
::: col
**Shipping Address**
123 Main St
New York, NY 10001
:::
::: col
**Billing Address**
456 Oak Ave
San Francisco, CA 94102
:::
:::

:::col uses {key="value"} syntax for width, vertical alignment, and background color:

::: columns
::: col {width="2/3" valign="top"}
Main content with more horizontal space.
:::
::: col {width="1/3" bg="#f4f4f5"}
Sidebar content.
:::
:::

Without width, columns split equally. Width fractions map to MJML percentage widths. Pixel values ("200px") and percentage values ("50%") are also accepted.

:::columns supports background image attributes on the opening line:

::: columns {bg-image="https://cdn.example.com/bg.jpg" bg-size="cover"}
::: col
Content over background image.
:::
:::

Flush sections ({flush})

Add {flush} to fuse consecutive :::columns (or :::section) blocks into a single <mj-wrapper>. This eliminates gaps between stacked sections – useful for hero-image-over-content patterns:

::: columns {flush bg="#1e3a5f"}
::: col
![Banner](https://cdn.example.com/hero.png)
:::
:::
 
::: columns {flush}
::: col
Content directly below the banner, no gap.
:::
:::

Consecutive {flush} sections merge into one <mj-wrapper>. The wrapper background color comes from the first section’s bg. Images inside flush sections default to padding="0" (compiler inference).

Mobile stacking ({mobile="inline"})

By default, columns stack vertically on mobile. Use {mobile="inline"} to prevent stacking – columns stay side-by-side by wrapping them in <mj-group>:

::: columns {mobile="inline"}
::: col {width="1/4"}
![Icon](https://cdn.example.com/icon.png)
:::
::: col {width="3/4"}
Text that stays beside the icon on mobile.
:::
:::

Block-level attributes can also be applied to content inside columns using {key="value"} syntax. See the email channel page for details.

:::section

Single-column layout shorthand. :::section is syntactic sugar for :::columns + :::col with one column. Use it when you need section-level attributes (background color, flush, padding) without multi-column layout.

::: section {bg="#f4f4f5" padding="spacious"}
Content with a background color, in a single column.
:::

Equivalent to:

::: columns {bg="#f4f4f5" padding="spacious"}
::: col
Content with a background color, in a single column.
:::
:::

:::section accepts all :::columns attributes: bg, padding, flush, mobile, bg-image, etc. It is transformed to :::columns + :::col at parse time, so all channel compilers handle it transparently.

:::list

Styled list.

::: list
- Choose your plan
- Add your team
- Start sending
:::

:::raw

Raw channel-native code. An escape hatch for channel-specific features that directives don’t cover.

::: raw
```html
<table style="width:100%">
  <tr><td>Custom HTML</td></tr>
</table>
```
:::

The content must be a fenced code block inside the directive.

:::highlight

Dark card with prominent text. Use for announcements, special offers, or key information that must stand out.

::: highlight
Limited-time offer: 50% off all plans!
:::

:::centered

Center-aligned text block. Use for taglines, thank-you messages, or any content that reads better centered.

::: centered
Thank you for being a customer.
:::

:::social

Social media icon links. Platforms are auto-detected from link URL hostnames: Facebook, X/Twitter, Instagram, LinkedIn, YouTube, GitHub, Pinterest, Dribbble, Medium, Snapchat, SoundCloud, Tumblr, Vimeo, Xing. Unknown URLs get a generic “web” icon.

::: social
[Facebook](https://facebook.com/yourpage)
[GitHub](https://github.com/yourrepo)
[LinkedIn](https://linkedin.com/company/yourco)
:::

Attributes: mode ("horizontal" default, "vertical"), align, size, padding.

::: social {mode="vertical" align="center"}
[Instagram](https://instagram.com/yourprofile)
[YouTube](https://youtube.com/yourchannel)
:::

Divider attributes

Thematic breaks (***) support block attributes for customizing the divider appearance:

***
{width="50%" color="#e4e4e7" thickness="2"}

Control flow directives

:::if / :::else

Conditional rendering. See the control flow page for full details.

::: if order.shipped
Your order has shipped!
:::else
Your order is being processed.
:::

:::each

Loop over an array. See the control flow page for full details.

::: each order.items as item
- {{item.name}} x {{item.qty}} -- ${{item.price}}
:::