Laravel Markdown Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-markdown
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\Markdown\MarkdownServiceProvider"
   

2. First Use Case: Render markdown in a Blade view:

   @markdown
       # Hello World
       This is **rendered** markdown.
   @endmarkdown
   

   Or programmatically:

   use Spatie\Markdown\MarkdownRenderer;
   
   $markdown = MarkdownRenderer::parse('# Hello World');
   echo $markdown;
   

3. Where to Look First:

   • README for basic usage.
   • config/markdown.php for configuration options.
   • app/Providers/AppServiceProvider.php to register custom parsers or extensions.

Implementation Patterns

Blade Component Usage

• Basic Rendering:

  @markdown
      Your markdown content here.
  @endmarkdown
  

• With Custom Class:

  @markdown(class="prose")
      # Heading
      Content with **styles**.
  @endmarkdown
  

• Inline Rendering:

  <p>Inline: @markdown('*italic*')</p>
  

Programmatic Rendering

• Default Renderer:

  $html = MarkdownRenderer::parse($markdownString);
  

• Custom Parsers:

  $renderer = app(MarkdownRenderer::class);
  $html = $renderer->parse($markdownString);
  

• Chaining Parsers:

  $renderer = MarkdownRenderer::create()
      ->useParser('extra')
      ->useParser('github')
      ->parse($markdownString);
  

Integration Tips

• Dynamic Content: Fetch markdown from a database or API and render it dynamically:

  $post = Post::find(1);
  $html = MarkdownRenderer::parse($post->content);
  

• Caching: Cache rendered markdown to improve performance:

  $cacheKey = 'markdown_' . md5($markdownString);
  $html = Cache::remember($cacheKey, now()->addHours(1), function () use ($markdownString) {
      return MarkdownRenderer::parse($markdownString);
  });
  

• Laravel Nova: Use the @markdown directive in Nova tooltips or field descriptions:

  <div class="form-help">
      @markdown
          This field is **required**.
      @endmarkdown
  </div>
  

Configuration

Extend the default parsers in config/markdown.php:

'parsers' => [
    'commonmark' => [
        'extra' => true,
        'tables' => true,
    ],
    'extra',
    'github',
],

Gotchas and Tips

Pitfalls

• XSS Vulnerabilities: Always sanitize user-provided markdown to prevent XSS attacks. Use Purifier or similar:

  use Spatie\Markdown\MarkdownRenderer;
  use Spatie\Markdown\Parsers\CommonMarkParser;
  
  $parser = new CommonMarkParser();
  $parser->setInput($markdownString);
  $parser->parse();
  $html = e($parser->getOutput()); // Escape output
  

• Parser Conflicts: Mixing parsers (e.g., commonmark + extra) may lead to unexpected behavior. Test thoroughly.
• Blade Escaping: The @markdown directive escapes HTML by default. Use @verbatim or {{ !! }} to bypass escaping if needed:

  @verbatim
      @markdown
          <script>alert('XSS')</script>
      @endmarkdown
  @endverbatim
  

Debugging

• Parser Errors: Enable debug mode in config/markdown.php to log parser errors:

  'debug' => env('MARKDOWN_DEBUG', false),
  

• Output Mismatches: Compare raw markdown with rendered HTML to identify missing features or syntax errors.

Tips

• Custom Parsers: Extend Spatie\Markdown\Parsers\Parser to create custom markdown processors:

  namespace App\Markdown;
  
  use Spatie\Markdown\Parsers\Parser;
  
  class CustomParser extends Parser
  {
      public function parse()
      {
          // Custom logic
          $this->output = 'Custom HTML';
      }
  }
  

  Register it in AppServiceProvider:

  MarkdownRenderer::create()->useParser(CustomParser::class);
  

• Syntax Highlighting: Integrate with libraries like Highlight.js or Prism.js for code blocks:

  @markdown
      ```javascript
      console.log('Hello');
      ```
  @endmarkdown
  <script src="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/prism.min.js"></script>
  

• Markdown Editor: Pair with a WYSIWYG editor (e.g., trix, ckeditor) for user-friendly markdown input:

  <input type="hidden" name="content" id="markdown-content">
  <trix-editor input="markdown-content"></trix-editor>
  

• Performance: Pre-render markdown during deployment or use queue jobs for large-scale rendering:

  MarkdownRenderer::parse($markdownString)->dispatch();
  

Extension Points

• Event Listeners: Listen to markdown parsing events (e.g., MarkdownParsed) for post-processing:

  event(new MarkdownParsed($markdownString, $html));
  

• Service Provider: Bind custom parsers or extend functionality in AppServiceProvider:

  public function boot()
  {
      MarkdownRenderer::macro('customMethod', function () {
          return 'Custom logic';
      });
  }