Php Markdown Laravel Package

Getting Started

1. Install via Composer: composer require michelf/php-markdown.
2. Use the Michelf\Markdown class for standard Markdown or Michelf\MarkdownExtra for extended syntax (tables, fenced code blocks, footnotes, etc.).
3. Convert Markdown to HTML in a single line:

   use Michelf\Markdown;
   $html = (new Markdown())->transform($markdownText);
   

4. First use case: rendering user-submitted content (e.g., blog comments, docs) safely and predictably—especially where rich formatting beyond plain HTML is needed.

Implementation Patterns

• Middleware for Markdown Content: In Laravel, create a middleware or helper to auto-convert .md files (e.g., for documentation routes or static pages).
• Hybrid Templates: Embed parsed Markdown inside Blade views using {!! $html !!} (remember to escape output when needed—e.g., avoid unsanitized user input).
• Service Classes: Encapsulate Markdown parsing in a service (e.g., MarkdownRenderer) for reuse across controllers, jobs, or queues.
• Per-Project Customization: Extend Markdown or MarkdownExtra to add custom reference definitions, syntax hooks, or override transformations (see transform() override points in docs).
• Laravel Blade Integration: Register a custom @markdown directive to enable @markdown…@endmarkdown blocks in Blade views.

Gotchas and Tips

• Output Escaping: transform() returns raw HTML—never use {{ $html }} in Blade (it double-escapes). Use {!! $html !!} only for trusted sources; sanitize user input with a library like HTML Purifier first.
• No HTML Sanitization: By default, the parser allows raw HTML (unless disabled via config or in Markdown Extra via html_markup). Consider setting html_markup = false in MarkdownExtra for stricter control.
• Fenced Code Blocks: To use them reliably, ensure your Markdown Extra parser is instantiated—e.g., new \Michelf\MarkdownExtra(). Standard Markdown ignores them.
• Reference-Style Links: These require unique link IDs and must be defined after the reference link text; placement matters (after main content is best practice).
• Debugging Misrendering: Enable Markdown::CODE_INCREMENT or use Xdebug to inspect internal state. Check for trailing whitespace in reference links (common source of errors).
• Performance: Parsing is lightweight but avoid repeated parsing in tight loops—cache parsed HTML for static content.
• Extended Syntax: For footnotes, tables, definition lists, or task lists, always use MarkdownExtra; standard Markdown won’t support them.
• Legacy Note: This package is stable and widely used, but the project is in maintenance mode—no active feature development. For newer features (e.g., GitHub Flavored Markdown), consider league/commonmark instead.