Marko.js v6 Technical Guide

Essential syntax, patterns, and common pitfalls for working with Marko.js v6 components.

📋 Table of Contents

Component Syntax
Body Content
Attributes
Conditionals
Common Pitfalls
Best Practices
Troubleshooting

Component Syntax

✅ Correct Syntax

1. Kebab-case Component Names

<!-- ✅ CORRECT: kebab-case -->
<my-component></my-component>
<user-card></user-card>
<alert-box></alert-box>

<!-- ❌ WRONG: PascalCase or camelCase -->
<MyComponent></MyComponent>
<myButton></myButton>

2. Self-closing Tags

<!-- ✅ CORRECT: space before slash -->
<icon name="check" />
<alert-box kind="tip" />

<!-- ❌ WRONG: no space -->
<icon name="check"/>
<alert-box kind="tip"/>

3. Attribute Values

<!-- ✅ CORRECT: unquoted for dynamic values -->
<a href=input.link>Link</a>
<div class=["active", input.isCurrent && "current"]></div>

<!-- ✅ CORRECT: quoted for static values -->
<a href="/about">About</a>
<div class="container">Content</div>

<!-- ❌ WRONG: quoted dynamic values -->
<a href="${input.link}">Link</a>
<div class="${input.class}">Content</div>

Body Content

✅ Rendering Body Content

To render the content between opening and closing tags:

<!-- ✅ CORRECT: Use input.content -->
<div class="my-component">
  <${input.content}/>
</div>

<!-- Usage in markdown -->
<my-component>
  This is the body content
</my-component>

❌ Common Mistakes

<!-- ❌ WRONG: Renders as <input class=text> HTML element -->
<div><input.text/></div>

<!-- ❌ WRONG: Renders as <input> HTML element -->
<div><input/></div>

<!-- ❌ WRONG: Renders as literal <body> tag -->
<div><body/></div>

<!-- ❌ WRONG: Expects input.renderBody which doesn't exist -->
<div><${input.renderBody}/></div>

Named Slots

For components with multiple content areas:

<!-- Component: card.marko -->
<div class="card">
  <if=input.header>
    <div class="card-header">
      <input.header/>
    </div>
  </if>
  <if=input.body>
    <div class="card-body">
      <input.body/>
    </div>
  </if>
  <if=input.footer>
    <div class="card-footer">
      <input.footer/>
    </div>
  </if>
</div>

<!-- Usage -->
<card>
  <card-header><h3>Title</h3></card-header>
  <card-body>Content here</card-body>
  <card-footer>Footer info</card-footer>
</card>

Attributes

✅ Dynamic Attributes

1. Array Syntax for Classes

<!-- ✅ CORRECT -->
<div class=["alert", input.kind && "alert-" + input.kind, !input.kind && "alert-default"]>
  Content
</div>

<!-- Results: -->
<!-- kind="note" → class="alert alert-note" -->
<!-- kind="tip" → class="alert alert-tip" -->
<!-- kind undefined → class="alert alert-default" -->

2. Fallback Values

<!-- ✅ CORRECT: || operator -->
<a href=input.link || "#">Link</a>

<!-- ✅ CORRECT: inline ternary -->
<div class=input.type ? "type-" + input.type : "type-default">
  Content
</div>

❌ Reserved HTML Attributes

AVOID these attribute names as they're reserved in HTML:

<!-- ❌ WRONG: type is reserved (used by input, button, etc.) -->
<alert-box type="note">Content</alert-box>

<!-- ✅ CORRECT: Use kind or variant instead -->
<alert-box kind="note">Content</alert-box>
<alert-box variant="note">Content</alert-box>

Other reserved names to avoid:

id - Use uid, itemId, etc.
class - Use className (but class is OK if using array syntax)
style - Use css or styles
name - Use kind, variant, etc.
value - Use defaultValue, content, etc.
for - Use htmlFor (label context)

Conditionals

✅ If Statement

<!-- ✅ CORRECT: no parentheses around expression -->
<if=input.isVisible>
  <div>This is visible</div>
</if>

<!-- ✅ CORRECT: with else -->
<if=input.type === "primary">
  <button-primary>Click</button-primary>
<else/>
  <button-secondary>Click</button-secondary>
</if>

<!-- ❌ WRONG: parentheses around expression -->
<if(input.isVisible)>
  <div>This is visible</div>
</if>

<!-- ❌ WRONG: if() syntax -->
<if(input.isVisible)>
  <div>This is visible</div>
</if>

✅ For Loops

<!-- ✅ CORRECT: pipe syntax -->
<for|item| of=input.items>
  <div>${item.name}</div>
</for>

<!-- ✅ CORRECT: with index -->
<for|item, index| of=input.items>
  <div>${index + 1}. ${item.name}</div>
</for>

<!-- ✅ CORRECT: range -->
<for|i| from=0 to=10>
  <div>Item ${i}</div>
</for>

Common Pitfalls

1. Comparison Operators in If-Attributes

CRITICAL: Marko v6 does NOT support >, <, >=, <= operators in <if> tag attributes. These are output as literal text.

<!-- ❌ WRONG: Outputs "0>" as text -->
<if=input.items.length > 0>
  Content
</if>

<!-- ❌ WRONG: Outputs "<" as text -->
<if=input.index < 10>
  Content
</if>

<!-- ✅ CORRECT: Compute in let variable first -->
<let/hasItems= (input.items && input.items.length)>
<if=hasItems>
  Content
</if>

<!-- ✅ CORRECT: For comparisons, use valid operators -->
<let/isValidIndex= (input.index <= 10)>
<if=isValidIndex>
  Content
</if>

2. Boolean Conversion for Variables

CRITICAL: When a <let> variable evaluates to 0, passing it to <if> outputs "0>" as text.

<!-- ❌ WRONG: Returns 0 for empty array, outputs "0>" -->
<let/hasChildren= (input.item.children && input.item.children.length)>
<if=hasChildren>
  Content
</if>

<!-- ✅ CORRECT: Use !! for proper boolean conversion -->
<let/hasChildren= !!(input.item.children && input.item.children.length)>
<if=hasChildren>
  Content
</if>

3. Self-Closing Custom Components

CRITICAL: Self-closing custom components may output /> as text in HTML.

<!-- ❌ WRONG: May output "/>" as text -->
<theme-toc-item item=item/>
<my-component data=input.data/>

<!-- ✅ CORRECT: Use explicit closing tags -->
<theme-toc-item item=item></theme-toc-item>
<my-component data=input.data></my-component>

<!-- ✅ OK: Self-closing HTML elements work fine -->
<img src=input.imagePath/>
<input value=input.text/>
<br/>

4. Template Literals in Attributes

<!-- ❌ WRONG: Not supported in Marko v6 -->
<div class="alert alert-${input.type}">
  Content
</div>

<!-- ✅ CORRECT: Use array syntax -->
<div class=["alert", "alert-" + input.type]>
  Content
</div>

<!-- ✅ CORRECT: Use ternary -->
<div class=input.type ? "alert alert-" + input.type : "alert">
  Content
</div>

2. Attribute Binding

<!-- ❌ WRONG: Quoted dynamic values -->
<div class="${input.className}">Content</div>

<!-- ✅ CORRECT: Unquoted for dynamic -->
<div class=input.className>Content</div>

<!-- ✅ CORRECT: Array for classes -->
<div class=["base-class", input.className]>Content</div>

3. Text Content

<!-- ✅ CORRECT: Direct text -->
<div>Hello ${input.name}</div>

<!-- ❌ WRONG: Using <input.text/> for body content -->
<div><input.text/></div>

<!-- ✅ CORRECT: For body content between tags -->
<div><${input.content}/></div>

4. Component Discovery

Problem: Components in tags/ directory not rendering

Solution:

Ensure tags are copied to build output
Use kebab-case filenames: alert-box.marko ✅, AlertBox.marko ❌
Rebuild after adding new components

Best Practices

1. Component Structure

<!-- ✅ GOOD: Clear, documented component -->
<!--
  Alert Box Component

  Types: note, tip, warning, danger, info, caution
  Example: <alert-box kind="warning">Important!</alert-box>
-->
<div class=["alert", input.kind && "alert-" + input.kind, !input.kind && "alert-note"]>
  <${input.content}/>
</div>

2. Attribute Naming

<!-- ✅ GOOD: Descriptive, non-conflicting names -->
<my-component
  kind="primary"       <!-- NOT type -->
  variant="large"      <!-- NOT size -->
  isDisabled=true      <!-- NOT disabled -->
  onItemClick=handleClick  <!-- NOT onClick -->
>
  Content
</my-component>

3. Default Values

<!-- ✅ GOOD: Provide sensible defaults -->
<div class=["base-class", input.modifier && "base-" + input.modifier]>
  <${input.content}/>
</div>

<a href=input.link || "#">
  <input.text/>
</a>

4. Conditional Rendering

<!-- ✅ GOOD: Simple conditionals -->
<if=input.showHeader>
  <div class="header">
    <input.header/>
  </div>
</if>

<!-- ✅ GOOD: Multiple conditions -->
<div class=[
  "alert",
  input.kind === "error" && "alert-error",
  input.kind === "warning" && "alert-warning",
  !input.kind && "alert-default"
]>
  <${input.content}/>
</div>

Troubleshooting

Problem: Component Shows Raw Template Syntax

Symptom:

<div class="alert alert-${input.type || 'note'}"><input class=text></div>

Causes:

Template literal used in attribute → Use array syntax
Tags directory not copied to dist → Ensure build copies tags
Component not discovered → Rebuild project

Problem: Body Content Not Rendering

Symptom:

<div class="alert"></div>
<!-- Content is missing -->

Causes:

Using <input.text/> → Use <${input.content}/>
Using <input/> → Use <${input.content}/>
Using <body/> → Use <${input.content}/>
Attribute name mismatch → Check component expects input.content

Problem: Attributes Not Being Passed

Symptom:

<!-- All components have default values -->
<div class="alert alert-note"></div>
<div class="alert alert-note"></div>

Causes:

Using reserved attribute name (e.g., type) → Use kind, variant, etc.
Attribute value not being passed → Check compiled output for function call
Component needs rebuild → Delete dist/ and rebuild

Problem: Build Errors

Common errors:

Tag does not support arguments. <if(expression)>

Solution: Change to <if=expression> (no parentheses)

Missing semicolon

Solution: Remove script blocks or fix syntax (Marko v6 has limited script support)

Quick Reference

Component Template

<!--
  Component Name

  Description of what it does

  Attributes:
    - kind: Component variant (required)
    - size: Size variant (optional, default: "medium")

  Example: <my-component kind="primary">Content</my-component>
-->

<div class=[
  "my-component",
  input.kind && "my-component-" + input.kind,
  input.size && "my-component-" + input.size
]>
  <${input.content}/>
</div>

Debugging Checklist

✅ Component name is kebab-case
✅ File is in tags/ directory
✅ Using <${input.content}/> for body content
✅ Not using reserved attribute names
✅ Using array syntax for dynamic classes
✅ Using <if=expression> not <if(expression)>
✅ NO comparison operators (>, <) in <if> attributes
✅ Using !! for boolean conversion in <let> variables
✅ Using explicit closing tags for custom components
✅ Rebuilt after changes
✅ Tags copied to dist/

Additional Resources

Marko Documentation: https://markojs.com/docs/
@marko/run Docs: https://github.com/marko-js/run
MarkoPress Component Guide: MARKO_COMPONENTS_GUIDE.md

Last Updated: 2025-01-17 (updated 2025-01-25)

Version: Marko.js v6, @marko/run v0.9.4

FilesExpand file tree

marko-v6-syntax.md

Latest commit

History

marko-v6-syntax.md

File metadata and controls

Marko.js v6 Technical Guide

📋 Table of Contents

Component Syntax

✅ Correct Syntax

1. Kebab-case Component Names

2. Self-closing Tags

3. Attribute Values

Body Content

✅ Rendering Body Content

❌ Common Mistakes

Named Slots

Attributes

✅ Dynamic Attributes

1. Array Syntax for Classes

2. Fallback Values

❌ Reserved HTML Attributes

Conditionals

✅ If Statement

✅ For Loops

Common Pitfalls

1. Comparison Operators in If-Attributes

2. Boolean Conversion for Variables

3. Self-Closing Custom Components

4. Template Literals in Attributes

2. Attribute Binding

3. Text Content

4. Component Discovery

Best Practices

1. Component Structure

2. Attribute Naming

3. Default Values

4. Conditional Rendering

Troubleshooting

Problem: Component Shows Raw Template Syntax

Problem: Body Content Not Rendering

Problem: Attributes Not Being Passed

Problem: Build Errors

Quick Reference

Component Template

Debugging Checklist

Additional Resources