WooNooW/MARKDOWN_SYNTAX_AND_VARIABLES.md

# Markdown Syntax & Variables - Analysis & Recommendations

## Current Issues

### 1. Card & Button Syntax
**Current:**
```markdown
[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
```markdown
[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)
```html
<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)
```markdown
> **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