WooNooW/MARKDOWN_SYNTAX_AND_VARIABLES.md

Markdown Syntax & Variables - Analysis & Recommendations

Current Issues

1. Card & Button Syntax

Current:

[card type="hero"]
Content here
[/card]

[button url="https://example.com" style="solid"]Click me[/button]

Problem: Not standard Markdown - uses WordPress-style shortcodes

2. Variable Naming Mismatch

Template uses: {order_item_table} (singular) Preview defines: order_items_table (plural) Result: Variable not replaced, shows as {orderitemtable} (underscores removed by some HTML sanitizer)

---

All Variables Used in Templates

Order Variables

• {order_number} - Order ID
• {order_date} - Order date
• {order_total} - Total amount
• {order_status} - Current status
• {order_url} - Link to view order
• {order_item_table} ⚠️ MISMATCH - Should be order_items_table

Customer Variables

• {customer_name} - Customer full name
• {customer_email} - Customer email
• {customer_username} - Username (for new accounts)
• {customer_password} - Temporary password (for new accounts)

Store Variables

• {store_name} - Store name
• {store_url} - Store URL
• {store_email} - Store contact email

Payment Variables

• {payment_method} - Payment method used
• {payment_status} - Payment status
• {transaction_id} - Transaction ID

Shipping Variables

• {shipping_address} - Full shipping address
• {tracking_number} - Shipment tracking number
• {carrier} - Shipping carrier

Date Variables

• {completion_date} - Order completion date
• {cancellation_date} - Order cancellation date

---

Recommendations

Option 1: Keep Current Syntax (Easiest)

Pros:

• No changes needed
• Users already familiar
• Clear boundaries for cards

Cons:

• Not standard Markdown
• Verbose

Action: Just fix the variable mismatch

Option 2: Simplified Shortcode

[card:hero]
Content here
[/card]

[button:solid](https://example.com)Click me[/button]

Pros:

• Shorter, cleaner
• Still clear

Cons:

• Still not standard Markdown
• Requires converter changes

Option 3: HTML + Markdown (Hybrid)

<div class="card card-hero">

**Content** with markdown

</div>

<a href="url" class="button">Click me</a>

Pros:

• Standard Markdown allows inline HTML
• No custom parsing needed

Cons:

• Verbose
• Less user-friendly

Option 4: Attributes Syntax (Most Markdown-like)

> **Order Number:** #{order_number}
> **Order Date:** {order_date}
{: .card .card-hero}

[Click me](https://example.com){: .button .button-solid}

Pros:

• More Markdown-like
• Compact

Cons:

• Complex to parse
• Not widely supported
• Users may not understand

---

Recommended Action Plan

Immediate Fixes (Priority 1)

1. ✅ Fix <br> rendering - DONE!
2. ⚠️ Fix variable mismatch:
   • Change order_item_table → order_items_table in DefaultTemplates.php
   • OR change order_items_table → order_item_table in EditTemplate.tsx preview
3. Add all missing variables to preview sample data

Short-term (Priority 2)

1. Document all variables - Create user-facing documentation
2. Add variable autocomplete in markdown editor
3. Add variable validation - warn if variable doesn't exist

Long-term (Priority 3)

1. Consider syntax improvements - Get user feedback first
2. Add visual card/button inserter - UI buttons to insert syntax
3. Add syntax highlighting in markdown editor

---

Variable Replacement Issue

The underscore removal ({order_item_table} → {orderitemtable}) suggests HTML sanitization is happening somewhere. Need to check:

1. Frontend: DOMPurify or similar sanitizer?
2. Backend: WordPress wp_kses() or similar?
3. Email client: Some email clients strip underscores?

Solution: Use consistent naming without underscores OR fix sanitizer to preserve variable syntax.

---

Next Steps

1. Fix variable naming mismatch
2. Test all variables in preview
3. Document syntax for users
4. Get feedback on syntax preferences
5. Consider improvements based on feedback