Package WordPress HTML-to-Markdown and add a self-contained Markdown-to-HTML parser

[chubes4]

Goal

Provide a generic, self-contained Markdown <-> HTML codec in PHP Toolkit by packaging the existing WordPress HTML API renderer for HTML-to-Markdown and implementing the missing PHP Markdown-to-HTML direction without embedding the current CommonMark vendor graph.

Existing Upstream

dmsnell/html-to-md is the existing WordPress-oriented HTML-to-Markdown implementation. It uses the WordPress HTML API, has no production Composer dependencies, supports standalone execution through bundled HTML API dependencies, and is already the selected conversion layer for WordPress/ai#845.

PHP Toolkit should coordinate with and package that renderer rather than create a competing HTML-to-Markdown serializer. Adoption should follow the correctness work in dmsnell/html-to-md#17 and differential validation against the toolkit and downstream corpora.

No corresponding self-contained PHP Markdown-to-HTML parser was found in that project, Dennis Snell's other public repositories, or WordPress core. That missing parser remains the primary implementation work for this issue.

Context

The Markdown component already owns practical Markdown <-> WordPress block conversion. MarkdownConsumer currently parses with league/commonmark, while MarkdownProducer contains a private HTML-to-Markdown token walk built on DataLiberationHTMLProcessor. MarkdownConsumer also records the architectural direction directly: a dedicated parser would improve complexity, bundle size, performance, and PHP compatibility.

A reusable HTML boundary is needed by consumers whose canonical composition is:

Markdown <-> HTML <-> WordPress blocks

Automattic/blocks-engine#1189 tracks removing Blocks Engine's duplicate League dependency graph. Automattic/blocks-engine#1523 established direct HTML interchange so it can consume an upstream codec without changing product contracts.

Proposed Surface

Provide small public primitives equivalent to:

$html = MarkdownToHtmlConverter::convert( $markdown, $options );
$markdown = HtmlToMarkdownConverter::convert( $html, $options );

The exact names should follow toolkit conventions. The important contract is direct Markdown <-> HTML conversion independent of WordPress block serialization. MarkdownConsumer and MarkdownProducer can compose those primitives for their existing block-facing APIs.

The HTML-to-Markdown primitive should package or adapt dmsnell/html-to-md. The Markdown-to-HTML primitive should be a bounded, self-contained PHP parser owned through the toolkit or a coordinated WordPress package.

Acceptance Criteria

• The Markdown component exposes direct Markdown-to-HTML and HTML-to-Markdown APIs.
• The direct APIs do not require a WordPress block round trip.
• HTML-to-Markdown reuses or directly coordinates with dmsnell/html-to-md rather than duplicating its renderer.
• The adopted renderer includes the list, table, code-fence, and invisible-marker correctness fixes tracked in dmsnell/html-to-md#17 or equivalent upstream fixes.
• The renderer has a stable package, autoload, versioning, and standalone-runtime contract suitable for PHP Toolkit consumers.
• Markdown-to-HTML uses a self-contained PHP parser without league/commonmark or its transitive vendor graph.
• Markdown-to-block and block-to-Markdown behavior composes through the shared HTML codec where appropriate.
• The existing private producer conversion is retired or reduced to a compatibility adapter over the shared renderer.
• Headings, paragraphs, emphasis, links, images, lists, blockquotes, code fences, thematic breaks, tables, raw HTML islands, and frontmatter boundaries have deterministic fixtures.
• Parsing and serialization have explicit input, nesting, definition, and output budgets with fail-closed diagnostics for malformed or adversarial input.
• Existing source-aware editing and opaque preservation behavior remain covered.
• Corpus, differential, fuzz, and performance tests establish behavior before embedded dependencies are removed.
• The component remains usable outside WordPress and in constrained PHP/Playground deployments.

Downstream Adoption

Once released, Blocks Engine can replace its League-backed MarkdownAdapter internals with the toolkit codec while preserving its optional adapter and result-envelope contracts. Static-site and Markdown-first WordPress products then share the maintained WordPress-oriented conversion primitives.

---

AI assistance disclosure: OpenAI gpt-5.6-sol via OpenCode inspected dmsnell/html-to-md, dmsnell/blocky-formats, WordPress core, PHP Toolkit, Blocks Engine, the public WordPress/AI integration tracker, and downstream conversion fixtures; ran the renderer's standalone test suite; and refined this issue's ownership and acceptance criteria. Chris Huber directed the scope and remains responsible for review.