Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#313 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
markdown, php
Área
api, backend

Línea de trabajo

Lee MarkdownConsumer y MarkdownProducer, incluido el recorrido de tokens privado de DataLiberationHTMLProcessor, y luego ejecuta la suite de pruebas independiente existente de dmsnell/html-to-md. Se considera terminado cuando existen APIs directas de Markdown-to-HTML y HTML-to-Markdown sin el grafo de dependencias de League, con las fixtures, el corpus, las pruebas diferenciales, de fuzzing y de rendimiento especificadas, y la cobertura del runtime independiente.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
PHP
Estrellas
62
Forks
23
Merge medio
4 h 12 min
PR fusionados (30 d)
1

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

  • Incluye un Dockerfile o un archivo de Docker Compose
  • Sin plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de WordPress/php-toolkit

Todos los issues de WordPress/php-toolkit

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.