Markdown Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require andchir/markdown-bundle
   

   Ensure erusev/parsedown (v1.7+) is installed as a dependency (handled automatically via composer require).

2. Enable the Bundle: Register in config/bundles.php:

   return [
       // ...
       Andchir\MarkdownBundle\MarkdownBundle::class => ['all' => true],
   ];
   

3. First Use Case: Use the Twig filter in a template to render Markdown:

   {{ myMarkdownContent | markdown }}
   

   Example: Display a blog post’s content field as HTML:

   <article>
       {{ post.content | markdown }}
   </article>
   

Implementation Patterns

Core Workflow: Rendering Markdown

• Twig Integration: Pipe Markdown strings through the markdown filter:

  {{ article.body | markdown({ safeMode: true }) }}
  

  Supports optional config:

  {{ note.text | markdown({
      urlsLinked: false,
      breaksEnabled: true,
      markupEscaped: true
  }) }}
  

• File-Based Markdown: Load and render Markdown from files using includeFileContent:

  {{ includeFileContent('path/to/file.md') | markdown }}
  

  Useful for static documentation or dynamic content stored in files.

Dynamic Content Updates

• Console Command: Sync file content to a database field (e.g., description) via:

  php bin/console markdown:action update_content {entity_type} {file_path_field} {target_field}
  

  Example: Update a Page entity’s description from file_content_path:

  php bin/console markdown:action update_content page file_content_path description
  

• Conditional Rendering: Fallback to file content if the field is empty:

  {% if page.description is not empty %}
      {{ page.description | markdown }}
  {% else %}
      {{ includeFileContent(page.file_content_path) | markdown }}
  {% endif %}
  

Configuration

• Global Defaults: Override defaults in config/packages/andchir_markdown.yaml (if supported; check bundle docs for exact structure). Example:

  andchir_markdown:
      default_options:
          safeMode: true
          urlsLinked: false
  

• Per-Entity Options: Store options in the entity (e.g., markdownOptions field) and pass dynamically:

  {{ content | markdown(page.markdownOptions) }}
  

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • The bundle claims Symfony 4.x support but was last updated for Symfony 5. Test thoroughly in your environment.
   • Fix: Pin erusev/parsedown to ^1.7 in composer.json to avoid compatibility issues.

2. Safe Mode Security:

   • safeMode: true strips HTML tags for security but may break intended formatting (e.g., <kbd>, <code>).
   • Tip: Use sparingly; sanitize input elsewhere if strict HTML control is needed.

3. File Path Handling:

   • includeFileContent uses relative paths. Ensure files are accessible from the project root or use absolute paths.
   • Tip: Store file paths in a consistent location (e.g., public/uploads/markdown/).

4. Console Command Quirks:

   • The update_content command assumes specific entity field names (file_content_path, description). Customize via bundle extension if needed.
   • Tip: Check the command’s source code (src/Command/MarkdownActionCommand) to override logic.

Debugging

• Markdown Parsing Errors:

  • Use safeMode: false temporarily to debug rendering issues (e.g., syntax errors in Markdown).
  • Tip: Validate Markdown with Dillinger or parsedown --help CLI tool.

• Twig Filter Not Found:

  • Verify the bundle is enabled in bundles.php and cleared cache:

    php bin/console cache:clear
    

Extension Points

1. Custom Parsedown Extensions:

   • Extend erusev/parsedown functionality by registering extensions in your service container:

     # config/services.yaml
     Andchir\MarkdownBundle\:
         resource: '../vendor/andchir/markdown-bundle/src/'
         exclude: '../vendor/andchir/markdown-bundle/src/{Entity,DependencyInjection,Command}'
     

   • Tip: Use ParsedownExtra for tables, footnotes, etc.:

     {{ content | markdown({ extensions: ['ParsedownExtra'] }) }}
     

2. Override Twig Filter:

   • Replace the default filter by binding a custom service:

     // src/Markdown/MarkdownExtension.php
     public function getFilters()
     {
         return [
             new \Twig\TwigFilter('markdown', [$this, 'convertMarkdown']),
         ];
     }
     

   • Register the service in services.yaml and tag it as a Twig extension.

3. Event Listeners:

   • Hook into the markdown.parse event (if supported) to modify parsing behavior dynamically. Check bundle events via:

     php bin/console debug:event-dispatcher
     

Performance

• Caching Rendered Markdown:
  • Cache the HTML output of frequently rendered Markdown (e.g., static docs) using Symfony’s cache system:

    {% cache app.markdown_cache %}
        {{ content | markdown }}
    {% endcache %}
    

  • Tip: Use stash for per-user caching if content varies by context.