Easyadmin Markdown Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require clementtalleu/easyadmin-markdown-bundle
   

   Ensure config/bundles.php includes the bundle (auto-enabled with Flex).

2. Add Importmap for EasyMDE In assets/app.js (or your importmap config):

   importmap.import('https://cdn.jsdelivr.net/npm/easymde/dist/easymde.min.js');
   importmap.import('https://cdn.jsdelivr.net/npm/easymde/dist/easymde.min.css');
   

3. First Use Case: Replace TextEditorField In your CRUD controller’s configureFields():

   use ClementTalleu\EasyAdminMarkdownBundle\Field\MarkdownEditorField;
   
   yield MarkdownEditorField::new('description', 'Description')
       ->setFormTypeOption('required', true);
   

Key Files to Review

• src/Field/MarkdownEditorField.php (core field logic)
• config/packages/easy_admin_markdown.yaml (default config)
• assets/controllers/easyadmin-markdown-bundle.js (client-side JS hooks)

Implementation Patterns

Workflow: Markdown in EasyAdmin

1. Form Editing

   • Replace TextEditorField with MarkdownEditorField for any text field needing Markdown.
   • Configure via setFormTypeOptions() (e.g., toolbar buttons, preview mode):

     yield MarkdownEditorField::new('content')
         ->setFormTypeOptions([
             'config' => [
                 'toolbar' => ['bold', 'italic', 'heading', '|', 'preview'],
                 'spellChecker' => false,
             ],
         ]);
     

2. Detail Page Rendering

   • Stored Markdown is auto-converted to sanitized HTML in detail views.
   • Customize rendering with setTemplate():

     ->setTemplate('easyadmin-markdown-bundle::field/markdown_detail.html.twig')
     

3. Asset Integration

   • Use AssetMapper (no manual builds). For custom CSS/JS, extend the bundle’s asset pipeline:

     // assets/controllers/easyadmin-markdown-bundle.js
     document.addEventListener('DOMContentLoaded', () => {
         const editor = EasyMDE.extend({
             spellChecker: false,
             customClass: 'my-custom-editor',
         });
         // ...
     });
     

Integration Tips

• Validation: Use Symfony’s Markdown constraint (e.g., new Markdown()) to validate syntax.
• Sanitization: Override getSanitizedHtml() in a custom field class to adjust DOMPurify rules.
• Localization: EasyMDE supports i18n via config.locale. Pass via setFormTypeOptions():

  ->setFormTypeOptions(['config' => ['locale' => 'fr']])
  

Gotchas and Tips

Pitfalls

1. Asset Loading

   • Issue: EasyMDE fails to load if importmap isn’t configured.
   • Fix: Verify easymde.min.js and .css are in your importmap. Test with:

     php bin/console assets:debug
     

2. Sanitization Overzealousness

   • Issue: Custom HTML tags (e.g., <figure>) may be stripped in detail views.
   • Fix: Extend MarkdownEditorField and override sanitizeHtml():

     public function sanitizeHtml(string $html): string {
         $config = DOMPurify::configuration();
         $config->ALLOWED_TAGS[] = 'figure';
         return DOMPurify::cleanHTML($html, $config);
     }
     

3. Conflict with Other Editors

   • Issue: Trix or CKEditor may interfere if both are on the page.
   • Fix: Scope EasyMDE to .markdown-editor via CSS:

     .markdown-editor { /* EasyMDE styles */ }
     

Debugging

• Console Errors: Check browser console for EasyMDE is not defined. Ensure importmap is loaded before EasyAdmin JS.
• Field Not Rendering: Verify the field is yielded after Crud::new() in your controller.
• Markdown Parsing: Use bin/console debug:config clement_talleu_easyadmin_markdown to inspect config.

Extension Points

1. Custom Toolbar Extend EasyMDE config via setFormTypeOptions():

   ->setFormTypeOptions([
       'config' => [
           'toolbar' => [
               'bold', 'italic', 'heading', '|',
               'quote', 'unordered-list', 'ordered-list', '|',
               'link', 'image', 'preview', 'side-by-side', 'fullscreen',
           ],
       ],
   ])
   

2. Plugin Integration Load EasyMDE plugins (e.g., EasyMDE.extend({ plugins: ['spellChecker'] })) by:

   • Adding plugin JS to importmap.
   • Initializing in easyadmin-markdown-bundle.js:

     const editor = EasyMDE.extend({
         plugins: ['spellChecker'],
         spellChecker: { /* options */ },
     });
     

3. Server-Side Processing Hook into onCrudAction() to process Markdown before save:

   public function configureActions(Actions $actions): Actions {
       $actions->add(Crud::NEW, Action::new()
           ->setHandler(function (EntityManagerInterface $em, $entity) {
               $entity->setProcessedContent(markdown($entity->getContent()));
               $em->flush();
           })
       );
   }