Markdown Laravel Package

Getting Started

1. Install via Composer: composer require cebe/markdown
2. Basic usage: In a Laravel controller or service, instantiate the parser and render Markdown:

   use cebe\markdown\Markdown;
   
   $markdown = new Markdown();
   $html = $markdown->parse('# Hello World');
   

3. Choose a dialect: Use Gfm or Extra classes for specific syntax. Note: GFM now handles inline HTML (e.g., <a> tags) more robustly with URLs/emails:

   use cebe\markdown\Gfm;
   $html = (new Gfm())->parse("Visit [Google](https://google.com) or email user@example.com");
   

4. First real-world use case: Render user-submitted Markdown content (e.g., blog comments or docs) while sanitizing output if needed. Leverage the improved inline HTML handling for richer content (e.g., embedded links in Markdown).

Implementation Patterns

• Laravel Service Binding: Register Markdown or Gfm as a singleton in AppServiceProvider:

  $this->app->singleton(\cebe\markdown\Gfm::class, fn() => new \cebe\markdown\Gfm());
  

• View Composers: Preprocess Markdown in Blade templates, now with better support for inline HTML:

  $view->with('content', $markdown->parse($post->body_markdown));
  

• Custom Syntax: Extend Gfm for advanced use cases (e.g., custom [[reference]] syntax). Avoid using [ as the first character in reference names to prevent conflicts:

  class CustomGfm extends Gfm {
      protected function parseReference($text) { /* Handle [[custom]] syntax */ }
  }
  

• Caching: Cache parsed HTML for performance, especially with static content leveraging the improved GFM features.

Gotchas and Tips

• Security first: Sanitize user-provided Markdown output (e.g., with HTMLPurifier) due to relaxed inline HTML handling in GFM. The package does not auto-sanitize.
• PHP version: Requires PHP ≥7.0 (unmaintained since 2018). For long-term projects, consider alternatives like league/commonmark.
• Inline HTML improvements: GFM now better preserves inline HTML (e.g., <a> tags) within Markdown. Test edge cases like nested tags or malformed HTML.
• Reference syntax: Avoid [ as the first character in custom references (e.g., [[ref]] works, [ref] may conflict). Use [[ for clarity.
• Debugging: Verify GFM vs. Markdown output differences (e.g., task lists, email/URL handling). Test with fixtures like:

  Visit [Google](https://google.com) or email user@example.com.
  

• Autoloading: Ensure Composer’s autoloader is up-to-date (composer dump-autoload) if classes fail to load.