Laravel Mailcoach Markdown Editor Laravel Package

Getting Started

Minimal Steps

1. Installation Require the package via Composer:

   composer require spatie/laravel-mailcoach-markdown-editor
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Spatie\MailcoachMarkdownEditor\MailcoachMarkdownEditorServiceProvider"
   

2. Enable in Mailcoach Configure Mailcoach to use this editor by setting the editor value to markdown in your config/mailcoach.php:

   'editor' => 'markdown',
   

3. First Use Case Navigate to Mailcoach’s email editor in your admin panel. The EasyMDE editor will now replace the default editor, allowing you to compose emails in Markdown.

Implementation Patterns

Usage Patterns

1. Editor Integration The package seamlessly integrates with Mailcoach’s existing email editor workflow. Developers don’t need to modify Mailcoach’s core logic—just enable the editor via config.

2. Customizing Editor Options Override default EasyMDE settings by publishing the config file and modifying config/mailcoach-markdown-editor.php:

   'options' => [
       'spellChecker' => false,
       'toolbar' => [
           'bold', 'italic', 'heading', '|',
           'quote', 'unordered-list', 'ordered-list', '|',
           'link', 'image', 'table', '|',
           'preview', 'side-by-side', 'fullscreen'
       ],
   ],
   

3. Extending Functionality Use EasyMDE’s API to add custom plugins or behaviors. For example, inject a custom toolbar button:

   // In a Mailcoach asset file (e.g., `resources/js/mailcoach.js`)
   EasyMDE.extend({
       name: 'customButton',
       action: (editor) => {
           editor.saveMarkdown();
           alert('Custom action triggered!');
       },
       className: 'custom-button',
       title: 'Custom Button'
   });
   

4. Handling Markdown Output Mailcoach automatically converts Markdown to HTML before sending emails. No additional processing is required unless you need to pre-process the Markdown (e.g., for custom syntax).

5. Localization Localize the editor’s UI by overriding EasyMDE’s language strings in your published config or via JavaScript:

   EasyMDE.lang = {
       ...EasyMDE.lang,
       preview: 'Vorschau (DE)' // Example German translation
   };
   

Gotchas and Tips

Pitfalls

1. Editor Not Loading

   • Cause: Missing JavaScript/CSS assets or incorrect config.
   • Fix: Ensure the package’s assets are published and included in your Mailcoach layout:

     php artisan vendor:publish --tag=mailcoach-markdown-editor-assets
     

     Add to your layout:

     @vite(['resources/js/mailcoach.js', 'vendor/spatie/mailcoach-markdown-editor/css/easymde.min.css'])
     

2. Markdown Not Rendering

   • Cause: Mailcoach’s HTML sanitizer stripping tags or EasyMDE output issues.
   • Fix: Adjust Mailcoach’s allowed_html config or debug EasyMDE’s output with:

     editor.saveMarkdown(); // Log this to console to verify Markdown.
     

3. Conflict with Other Editors

   • Cause: Multiple editor packages installed or conflicting assets.
   • Fix: Disable other editors in config/mailcoach.php and clear cached views:

     php artisan view:clear
     

4. Performance Issues

   • Cause: Large Markdown files or excessive plugins.
   • Fix: Disable unused EasyMDE plugins or lazy-load the editor.

Debugging

• Console Logs: Use console.log(editor.getValue()) in browser dev tools to inspect Markdown content.
• Network Tab: Verify EasyMDE assets (JS/CSS) are loading without 404 errors.
• Mailcoach Logs: Check storage/logs/laravel.log for editor-related errors.

Tips

1. Custom CSS/JS Override EasyMDE’s styles by targeting .EasyMDE in your CSS or extend its API as shown above.

2. Preview Mode Enable side-by-side preview in config for better WYSIWYG feedback:

   'options' => ['sideBySidePreview' => true],
   

3. Fallback for Non-Markdown Users Provide a toggle to switch between Markdown and HTML modes by extending the editor UI:

   editor.codemirror.on('change', () => {
       if (editor.isPreviewMode()) {
           // Optionally sync with a hidden HTML field.
       }
   });
   

4. Testing Test Markdown rendering in Mailcoach’s preview pane before sending emails to avoid surprises.

5. Updates Monitor Mailcoach’s docs for breaking changes in newer versions of this package or EasyMDE.