Html To Markdown Laravel Package

Getting Started

1. Install the package via Composer:

   composer require league/html-to-markdown
   

2. Ensure required PHP extensions (dom, xml, libxml) are enabled.
3. Create and use a basic converter:

   use League\HTMLToMarkdown\HtmlConverter;
   
   $converter = new HtmlConverter();
   $markdown = $converter->convert('<h1>Hello World</h1>');
   echo $markdown; // => "# Hello World"
   

First use case: convert rich-text HTML content (e.g., from a CMS or user input) into clean Markdown for storage, editing, or export (e.g., to plain-text email).

Implementation Patterns

• Sanitization-first conversion for untrusted input:
  Combine with HTMLPurifier and use strip_tags/remove_nodes options:

  $converter = new HtmlConverter([
      'strip_tags' => true,
      'remove_nodes' => 'script iframe object',
  ]);
  

• Custom converters: Extend existing converters or add new ones (e.g., custom TableConverter for table support):

  $converter->getEnvironment()->addConverter(new MyCustomConverter());
  

• Project-wide configuration: Reuse a configured instance (e.g., in a service container or singleton):

  $converter = new HtmlConverter([
      'header_style' => 'atx',
      'italic_style' => '*',
      'bold_style' => '**',
      'hard_break' => true,  // GitHub-style line breaks
  ]);
  

• Preserve metadata: Use preserve_comments to retain CMS-specific comments (e.g., <!-- {title} -->) for round-trip editing workflows.

Gotchas and Tips

• HTML escaping: The package escapes * and _ in text nodes by default (v4.0.1+), but still may mangle math or code blocks—test with edge cases.
• Missing features: Tables and nested lists require explicit Converter\TableConverter (and custom handling for nested lists—see To-Do list in README).
• DOMDocument quirks: Invalid HTML can cause parsing errors. Wrap convert() in libxml_use_internal_errors(true) + libxml_get_errors() if pre-parsing is needed.
• Whitespace sensitivity: div is treated as block-level (v3.0.0+); newlines appear around div content—configure line-break behavior via hard_break and test with <div><p>...</p></div>.
• Link/output hygiene: Use strip_placeholder_links to remove empty links (e.g., <a href="#">), and use_autolinks to control link syntax ([text](url) vs <url>).
• Testing tip: Use HTML fixtures and compare against expected Markdown using loose equality (ignore trailing whitespace/newlines).