Parsedown Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run:

   composer require demontpx/parsedown-bundle ^1.3
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Demontpx\ParsedownBundle\DemontpxParsedownBundle::class => ['all' => true],
   ];
   

   (No AppKernel.php needed for Symfony 4+.)

2. First Use Case Use the Twig filter in a template:

   {{ '# Hello, Markdown!'|markdown }}
   

   Outputs: <h1>Hello, Markdown!</h1>

Implementation Patterns

Core Workflows

1. Twig Integration

   • Use |markdown filter for inline parsing:

     {% set content = '# Heading\n- List item' %}
     {{ content|markdown }}
     

   • Chain with other filters:

     {{ markdown_content|striptags|truncate(100) }}
     

2. Service Injection Inject the Parsedown service in controllers/services:

   use Demontpx\ParsedownBundle\Service\Parsedown;
   
   public function __construct(Parsedown $parsedown) {
       $this->parsedown = $parsedown;
   }
   
   public function renderMarkdown(string $text): string {
       return $this->parsedown->text($text);
   }
   

3. API Endpoint Enable the REST endpoint via config/routes.yaml:

   demontpx_parsedown:
       resource: "@DemontpxParsedownBundle/Resources/config/routing.yml"
       prefix: /api/parsedown
   

   Send a POST request with raw markdown to /api/parsedown for HTML output.

4. Dynamic Content Parse markdown from database fields or user input:

   {{ article.body|markdown }}
   

Integration Tips

• Custom Extensions: Extend Parsedown via Symfony’s compiler pass or override the service definition.
• Caching: Cache parsed HTML if markdown content is static (e.g., blog posts).
• Security: Sanitize input markdown to prevent XSS (e.g., use htmlspecialchars on untrusted input).

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch

   • The bundle targets Symfony 3.x/4.x. For Symfony 5+, check compatibility or fork the bundle.
   • Fix: Use demontpx/parsedown-bundle:dev-main if targeting newer Symfony.

2. Twig Auto-Reloading

   • Twig templates may not auto-reload after adding |markdown if the bundle isn’t properly registered.
   • Fix: Clear cache (php bin/console cache:clear) or restart the dev server.

3. API Endpoint CORS

   • The /parsedown endpoint lacks CORS headers by default, blocking frontend requests.
   • Fix: Add CORS middleware or configure Symfony’s NelmioCorsBundle.

4. Markdown Edge Cases

   • Some markdown features (e.g., tables, footnotes) may not render as expected.
   • Tip: Use Parsedown Extra for advanced syntax:

     $parsedown->useMarkdownExtra();
     

Debugging

• Check Service Availability Verify the service is registered:

  php bin/console debug:container demontpx_parsedown.parsedown
  

• Log Parsed Output Debug Twig filters with:

  {{ dump(markdown_content|markdown) }}
  

• Validate Input Ensure markdown input isn’t corrupted (e.g., truncated or malformed).

Extension Points

1. Override Parsedown Service Define a custom service in config/services.yaml:

   Demontpx\ParsedownBundle\Service\Parsedown:
       arguments:
           $extensions: ['!tag parser', '!autolink'] # Disable extensions
   

2. Add Custom Extensions Create a compiler pass to inject extensions:

   use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
   use Symfony\Component\DependencyInjection\ContainerBuilder;
   
   class AddCustomExtensionsPass implements CompilerPassInterface {
       public function process(ContainerBuilder $container) {
           $definition = $container->findDefinition('demontpx_parsedown.parsedown');
           $definition->addMethodCall('useCustomExtension', [new CustomExtension()]);
       }
   }
   

   Register the pass in DemontpxParsedownBundle.php.

3. Twig Filter Customization Override the Twig filter globally:

   // config/packages/twig.yaml
   twig:
       filters:
           markdown:
               method: customMarkdownFilter
               class: App\Twig\CustomExtension