html-to-markdown

html-to-markdown (Composer package league/html-to-markdown) parses an HTML document into a DOM tree and walks it from the most deeply nested nodes outward, converting each element into its Markdown equivalent. It’s the inverse of tools like league/commonmark: instead of rendering Markdown to HTML, it’s used to make existing HTML content editable as Markdown, convert HTML email into readable plain text, or migrate CMS content stored as HTML into Markdown-based systems.

Part of The League of Extraordinary Packages, the library ships a pluggable Environment/Converter system (header, list, table, link, image, code, blockquote converters, etc.) so behavior can be extended or overridden, plus configuration options for header style (ATX vs Setext), bold/italic markers, hard line breaks, autolinking, tag stripping, and comment preservation. Markdown tables are opt-in since they aren’t part of the original Markdown spec.

What You Get

• HtmlConverter::convert() for one-line HTML-to-Markdown conversion with sensible defaults
• A pluggable Environment/ConverterInterface system covering headers, lists, tables, links, images, code blocks, blockquotes, and more, each independently overridable or extendable
• Configuration options for header style (ATX vs Setext), bold/italic markers, hard vs soft line breaks, autolinking, and preserving or stripping specific tags/comments
• Optional TableConverter for Markdown tables (opt-in since tables aren’t part of the original Markdown spec)
• A bundled bin/html-to-markdown CLI for quick command-line conversion alongside the library API

Common Use Cases

• Converting HTML content stored in a legacy CMS into Markdown for a static-site or Markdown-based rewrite
• Turning HTML emails into clean plain-text/Markdown equivalents for previews or plain-text fallbacks
• Letting non-technical editors edit HTML-origin content in a friendlier Markdown editor
• Sanitizing and simplifying arbitrary HTML input by stripping unsupported tags before storage or display

Under The Hood

Architecture - HtmlConverter loads input HTML into a DOMDocument, then Environment walks the tree depth-first, dispatching each Element to the registered Converter\*Converter (Header, List, Table, Link, Image, Code, Blockquote, etc.) that matches its tag, accumulating Markdown output bottom-up from the most deeply nested nodes to the root. Tech Stack - Pure PHP (^7.2.5 || ^8.0) with only PHP’s built-in ext-dom and ext-xml extensions as runtime requirements, and dev tooling spanning PHPUnit, PHPStan, Psalm, and PHP_CodeSniffer for static analysis and testing. Code Quality - The tests/ directory exercises the full converter suite plus configuration option combinations, backed by three separate static analysis tools (PHPStan, Psalm, PHPCS) run in the composer test script, reflecting the strict quality bar The League of Extraordinary Packages holds its libraries to, though recent commit activity has slowed relative to the project’s 2011 creation and 32 releases. API Design - The single-call $converter->convert($html) covers the common case, while getConfig()->setOption() and getEnvironment()->addConverter() expose deep customization (styles, tag stripping, custom converters) without complicating the default path — an approachable API backed by a genuinely extensible converter registry.