Markdown Directives

Markdown directives are custom syntax elements that add interactive UI components — form inputs, buttons, and containers — directly into documents. They follow a consistent double-brace syntax and integrate with macros via the hai.doc library.

Syntax:

{{tagName attribute="value" booleanAttribute}}

{{tagName attribute="value"}}content{{/tagName}}

Quick Reference

Form directives

Directive	Self-closing	Description
button	Yes	Triggers a macro or snippet on click
checkbox-group	No	Group of toggleable checkboxes
datalist	No	Searchable dropdown with free-text fallback
input	Yes	Single-line text, date, or datetime field
option	Yes	An item within checkbox-group, datalist, radio-group, or select
radio-group	No	Single-selection button group
select	No	Fixed-choice dropdown
textarea	No	Multi-line text field

Container directives

Directive	Description
span	Inline container for text or inline elements
div	Generic block container with optional visual and action features
note	Styled callout block with optional type, title, and action buttons

Global attributes

Attribute	Applies to	Description
id	All	Unique identifier; used with hai.doc query methods
class	All	Space-separated CSS class names; also controls built-in behaviors

Built-in class names

Class	Effect
commit	Adds a button to replace the element with its inner content
copy	Adds a button to copy content to clipboard (as HTML)
fold	Adds a collapse/expand toggle
remove	Adds a button to delete the element
primary, secondary, tertiary	Presentation styles
info, tip, success, warning, error	Semantic color styles

Global Attributes

id

A unique identifier for the directive within the document. Required when targeting the element with macros.

{{input id="customer-name"}}

{{div id="summary-section"}}content{{/div}}

class

Space-separated CSS class names. In addition to custom styling, several built-in class names enable interactive behaviors (see Built-in class names above).

{{div class="fold"}}Collapsible section{{/div}}

{{div class="commit copy"}}Content with two actions{{/div}}

Form Directives

button

Triggers a snippet or macro when clicked.

Syntax: {{button ...attributes}}

Attributes

Attribute	Required	Default	Description
onclick	Yes	—	Snippet or macro trigger. Format: $Name or $Name[ordinal]
text	Yes	—	Label displayed on the button

Examples

{{button onclick="$SaveDraft" text="Save"}}

{{button onclick="$DeleteItem" text="Delete" class="danger"}}

{{button onclick="$ProcessOrder[2]" text="Process" class="success"}}

checkbox-group

Renders a group of checkboxes. Each option is a nested option directive.

Syntax:

{{checkbox-group ...attributes}}
  {{option value="..."}}
  {{option value="..." label="..."}}
{{/checkbox-group}}

Attributes

Attribute	Required	Default	Description
value	No	—	Comma-separated list of checked values
column	No	—	Boolean. Stacks checkboxes vertically

Examples

{{checkbox-group value="email,sms" column}}
  {{option value="email" label="Email"}}
  {{option value="sms" label="SMS"}}
  {{option value="phone" label="Phone"}}
{{/checkbox-group}}

datalist

A searchable dropdown that also accepts free-text entry.

Syntax:

{{datalist ...attributes}}
  {{option value="..."}}
{{/datalist}}

Attributes

Attribute	Required	Default	Description
placeholder	No	—	Hint text when nothing is selected
value	No	—	Currently selected or entered value
cols	No	—	Width in characters. Use fill for 100% width. Defaults to content width when omitted

Examples

{{datalist placeholder="Select your role"}}
  {{option value="Developer"}}
  {{option value="Designer"}}
  {{option value="Manager"}}
{{/datalist}}

{{datalist cols="30" placeholder="Select your role"}}
  {{option value="Developer"}}
  {{option value="Designer"}}
{{/datalist}}

input

Single-line text, number, date, or datetime-local field.

Syntax: {{input ...attributes}}

Attributes

Attribute	Required	Default	Description
type	No	text	text | number | date | datetime-local
placeholder	No	—	Hint text when empty
value	No	—	Current value
cols	No	20	Width in characters (text, number). Use fill for 100% width. date/datetime-local support fill only.
commit	No	—	Boolean. Replaces the input with its value on entry

Example

{{input type="text" placeholder="Your name"}}

{{input type="text" placeholder="Your name" value="Alice"}}

{{input type="text" placeholder="Your name" cols="fill"}}

{{input type="text" placeholder="Quick entry" class="commit"}}

{{input type="date"}}

{{input type="datetime-local" value="1970-01-01T00:00"}}

option

A single option used inside checkbox-group, datalist, radio-group, or select.

Syntax: {{option ...attributes}}

Attributes

Attribute	Required	Default	Description
value	Yes	—	The option's value
label	No	Same as value	Display text shown to the user

Examples

{{option value="Yes"}}

{{option value="1" label="Yes"}}

---

radio-group

Single-selection button group. Each option is a nested option directive.

Syntax:

{{radio-group ...attributes}}
  {{option value="..."}}
{{/radio-group}}

Attributes

Attribute	Required	Default	Description
value	No	—	Value of the selected option
column	No	—	Boolean. Stacks radio buttons vertically

Example

{{radio-group value="medium" column}}
  {{option value="low" label="Low"}}
  {{option value="medium" label="Medium"}}
  {{option value="high" label="High"}}
{{/radio-group}}

select

Fixed-choice dropdown. Each option is a nested option directive.

Syntax:

{{select ...attributes}}
  {{option value="..."}}
{{/select}}

Attributes

Attribute	Required	Default	Description
placeholder	No	—	Hint text when nothing is selected
value	No	—	Value of the selected option
cols	No	—	Width in characters (min-width floor; grows to the selected label). Use fill for 100% width

Example

{{select placeholder="Priority" value="Medium"}}
  {{option value="Low"}}
  {{option value="Medium"}}
  {{option value="High"}}
{{/select}}

{{checkbox-group column value="foo,baz"}}
    {{option value="foo"}}
    {{option value="bar" label="Bar Label"}}
    {{option value="baz"}}
{{/checkbox-group}}

textarea

Multi-line text input.

Syntax: {{textarea ...attributes}}content{{/textarea}}

Attributes

Attribute	Required	Default	Description
placeholder	No	—	Hint text when empty
rows	No	2	Height in lines. Auto-resizes to content
cols	No	fill	Width in characters (fill = 100% width)
commit	No	—	Boolean. Replaces the textarea with its content on entry

Example

{{textarea placeholder="Describe the issue..." rows="6"}}{{/textarea}}

Container Directives

note

A styled callout block with optional type-specific colors and action buttons.

Syntax:

{{note ...attributes}}
  content
{{/note}}

Attributes

Attribute	Required	Default	Description
type	No	—	info | tip | success | warning | error | danger — sets color and icon
title	No	Type name	Heading text. Defaults to the type name when type is set
fold	No	—	Boolean. Adds collapse/expand toggle
commit	No	—	Boolean. Adds button to unwrap content
copy	No	—	Boolean. Adds button to copy content to clipboard
remove	No	—	Boolean. Adds button to delete the note

Example

{{note type="warning" title="Before you proceed" fold}}
  Check that all required fields are filled in before submitting.
{{/note}}

div

Generic block container with optional visual emphasis and action buttons.

Syntax:

{{div ...attributes}}
  content
{{/div}}

Attributes

Attribute	Required	Default	Description
panel	No	—	Boolean. Applies panel styling (background, border, padding)
fold	No	—	Boolean. Adds collapse/expand toggle
commit	No	—	Boolean. Adds button to unwrap content
copy	No	—	Boolean. Adds button to copy content to clipboard
remove	No	—	Boolean. Adds button to delete the div

Example

{{div panel fold}}
  ## Action Items
  {{textarea placeholder="List action items..." rows="4"}}
{{/div}}

span

Inline container for wrapping text or inline elements with optional action buttons.

Syntax: {{span ...attributes}}inline content{{/span}}

Attributes

Attribute	Required	Default	Description
commit	No	—	Boolean. Adds button to unwrap content
copy	No	—	Boolean. Adds button to copy content to clipboard
remove	No	—	Boolean. Adds button to delete the span

Example

Customer {{span commit}}{{input placeholder="Name"}}{{/span}} placed an order.

Tips and best practices

• Save frequent patterns as snippets. A snippet named DatePicker containing {{input type="date"}} can be inserted anywhere with /DatePicker.
• Use meaningful id values. Descriptive IDs make it easier to target directives with hai.doc.getDirectiveById().
• Group related fields. Wrap related inputs in a div or note for logical organization and shared actions.
• Use commit for finalization. Templates that should produce plain text output should use commit on containers.
• Add fold to long sections. Collapsible sections keep complex documents manageable.
• Enable quick input mode (Cmd/Ctrl + Alt + Q) for rapid sequential form filling.
• Choose the right input type. Use type="date" or type="datetime-local" instead of text fields for temporal data.