docs: Consolidate documentation - 52% reduction (56 → 27 files)
✅ Documentation Cleanup: - Deleted 30 obsolete/completed docs - Created NOTIFICATION_SYSTEM.md (consolidates all notification docs) - Reduced from 56 to 27 MD files (52% reduction) 🗑️ Removed Categories: - Completed features (ALL_ISSUES_FIXED, BASIC_CARD_COMPLETE, etc.) - Superseded plans (NOTIFICATION_STRATEGY, NOTIFICATION_REFACTOR_*, etc.) - Duplicate/fragmented docs (MARKDOWN_*, TEMPLATE_*, etc.) 📝 Consolidated: - All notification documentation → NOTIFICATION_SYSTEM.md - Architecture & flow - Markdown syntax reference - Variables reference - Backend integration details - API endpoints - Email queue system - Global system toggle - Q&A section ✅ Kept Essential Docs (27): - Core architecture guides - Addon development guides - Feature-specific docs (shipping, payment, tax) - Implementation guides (i18n, hooks) - Project docs (README, PROJECT_BRIEF, PROJECT_SOP) 📊 Result: - Clearer navigation - Less confusion - Single source of truth for notifications - Easier for new developers
This commit is contained in:
dwindown
@@ -1,170 +0,0 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user