Markdown Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require graham-campbell/markdown
   

   Publish the config (optional):

   php artisan vendor:publish --provider="GrahamCampbell\Markdown\MarkdownServiceProvider" --tag="config"
   

2. First Use Case: Convert Markdown to HTML in a Blade view:

   {!! Markdown::parse('# Hello World') !!}
   

   Or in a controller:

   use GrahamCampbell\Markdown\Facades\Markdown;
   $html = Markdown::parse('**Bold text**');
   

3. Where to Look First:

   • README for basic usage.
   • config/markdown.php for configuration options (e.g., extensions, caching).
   • CommonMark Spec for supported syntax.

Implementation Patterns

Core Workflows

1. Blade Integration: Use Markdown::parse() in Blade templates for dynamic content:

   <div class="content">
       {!! Markdown::parse($post->body) !!}
   </div>
   

2. API Responses: Return parsed Markdown in API responses:

   return response()->json([
       'content' => Markdown::parse($request->markdown_content)
   ]);
   

3. Caching Parsed Output (via config):

   // config/markdown.php
   'cache' => true,
   

   Cache key is auto-generated from input.

4. Extensions: Enable/disable CommonMark extensions (e.g., tables, footnotes):

   Markdown::enableExtensions(['tables']);
   

5. Custom Parsing Logic: Chain methods for pre/post-processing:

   $html = Markdown::parse($text)
       ->replace('<h1>', '<h1 class="custom">')
       ->stripTags('<script>');
   

Integration Tips

• Form Requests: Sanitize Markdown input before parsing (e.g., strip HTML tags).
• Live Preview: Use with frontend frameworks (e.g., Alpine.js) for real-time updates:

  document.getElementById('preview').innerHTML = await fetch('/parse', {
      method: 'POST',
      body: JSON.stringify({ markdown: input.value })
  }).then(r => r.text());
  

• Testing: Mock the facade for unit tests:

  $this->app->instance(\GrahamCampbell\Markdown\Facades\Markdown::class, $mock);
  

Gotchas and Tips

Pitfalls

1. XSS Risks:

   • Issue: Markdown parsing can expose XSS if input isn’t sanitized.
   • Fix: Use Markdown::parse()->toHtml() with strip_tags() or a whitelist:

     $safeHtml = strip_tags(Markdown::parse($input), '<p><a><strong><em>');
     

2. Caching Quirks:

   • Issue: Cache may serve stale content if input changes slightly (e.g., whitespace).
   • Fix: Disable caching for dynamic content or use a custom cache key:

     Markdown::parse($text, null, 'custom_key_' . md5($text));
     

3. Extension Conflicts:

   • Issue: Enabling conflicting extensions (e.g., autolink + strikethrough) may break rendering.
   • Fix: Test extensions in isolation or refer to CommonMark docs.

4. Performance:

   • Issue: Parsing large Markdown files (e.g., 10KB+) can slow responses.
   • Fix: Cache aggressively or lazy-load content.

Debugging

• Inspect Parsed Output:

  $parsed = Markdown::parse($text);
  dd($parsed->toHtml()); // Debug HTML output
  

• Check Extensions:

  dd(Markdown::getExtensions()); // List enabled extensions
  

• Common Errors:
  • Undefined extension: Ensure the extension name matches CommonMark’s (e.g., tables, not table).
  • Cache not working: Verify file or array cache driver is configured in config/cache.php.

Extension Points

1. Custom Extensions: Register a League CommonMark extension via the config:

   // config/markdown.php
   'extensions' => [
       \League\CommonMark\Extension\MyCustomExtension::class,
   ],
   

2. Pre/Post Processing: Override the Markdown facade to add logic:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       $this->app->resolving(\GrahamCampbell\Markdown\Facades\Markdown::class, function ($markdown) {
           $markdown->afterParse(function ($html) {
               return str_replace('<h1>', '<h1 data-tracked>', $html);
           });
       });
   }
   

3. Environment-Specific Config: Use Laravel’s config caching to switch settings per environment:

   // config/markdown.php
   'cache' => env('MARKDOWN_CACHE', false),