thephpleague/html-to-markdown: PHP HTML Conversion and Configuration

Why thephpleague/html-to-markdown Exists

The library addresses the reverse of the more common Markdown to HTML workflow: it takes an HTML string and returns Markdown text. The README identifies several use cases, including making an existing HTML document editable by people who prefer Markdown, storing new content as HTML while editing it as Markdown, and converting HTML email to plain text. The audience is therefore PHP developers who have HTML in hand and need a Markdown representation without requiring users to edit the original markup directly.

The core promise is deliberately narrow. It is a conversion library, not an editor, storage system, or HTML validation service. That distinction matters when an application accepts content from users. The library can leave HTML elements such as `<span>`, `<div>`, `<iframe>`, and `<script>` in the result when no Markdown equivalent exists. Its documented behavior gives the caller control over that output, but it does not decide whether the original HTML is safe.

The HtmlConverter Conversion Flow

The documented entry point is `League\HTMLToMarkdown\HtmlConverter`. An application constructs an `HtmlConverter`, passes HTML to `convert()`, and receives a Markdown string. The README does not provide the internal parser architecture, so it would be misleading to describe a particular DOM implementation or traversal order. The observable API is configuration around conversion rather than a separately documented pipeline.

The converter handles ordinary Markdown-compatible constructs, including headings, emphasis, bold text, links, paragraphs, and line breaks. It also exposes options for cases where the HTML contains elements that do not map cleanly to Markdown. Configuration can be supplied when the converter is created or changed through `getConfig()->setOption()`. This means an application can establish a base policy in the constructor and adjust individual settings later, although the README does not document runtime concurrency behavior or configuration persistence.

One important default is that comments are removed. Placeholder links are retained by default. Unsupported tags are also preserved by default unless the caller changes `strip_tags` or `remove_nodes`. Those defaults are useful for avoiding accidental data loss, but they make conversion output policy-sensitive for imported documents.

Installation and First PHP Conversion

The project requires PHP 7.2 or later. The README instructs users to install the package with Composer and load Composer's autoloader. The example then converts a heading and prints the resulting Markdown.

Install the package in the PHP project:

composer require league/html-to-markdown

Create a script that loads the autoloader, creates `HtmlConverter`, and converts an HTML string:

<?php
require 'vendor/autoload.php';

use League\HTMLToMarkdown\HtmlConverter;

$converter = new HtmlConverter();
$html = "<h3>Quick, to the Batpoles!</h3>";
$markdown = $converter->convert($html);
echo $markdown;

The README states that the output is `### Quick, to the Batpoles!`. The included `demo` directory is also identified as a form for trying HTML to Markdown conversion. The repository includes `bin/`, `src/`, and `tests/`, but the README does not give a separate command for running the demo or a specific command for the test suite.

Controlling Unsupported HTML and Comments

The configuration model gives distinct answers to two questions: should an unsupported tag remain in the Markdown, or should its content also disappear? Setting `strip_tags` to `true` removes tags without Markdown equivalents while retaining the text inside them. This is suitable when a `<span>` or `<div>` is merely a formatting wrapper.

$converter = new HtmlConverter(array('strip_tags' => true));
$html = '<span>Turnips!</span>';
$markdown = $converter->convert($html);

The README says the result contains `Turnips!`. If the entire element and its contents should be discarded, use `remove_nodes` with a space-separated tag list.

$converter = new HtmlConverter(array('remove_nodes' => 'span div'));
$html = '<span>Turnips!</span><div>Monkeys!</div>';
$markdown = $converter->convert($html);

In this example, the result is empty because both tags and their contents are removed. Comments are stripped by default, but `preserve_comments` can be set to `true` or to an array of exact comment strings. This is a useful distinction for archived content where comments may carry meaningful application data, although the README does not describe comment formatting beyond the examples.

Choosing Link, Style, and Break Output

Conversion can be aligned with a target Markdown dialect or house style through several options. Bold text uses asterisks by default, while italic text uses the underlined syntax. The `bold_style` and `italic_style` options change those markers. The following configuration produces `*Italic*` and `__bold__`.

$converter = new HtmlConverter();
$converter->getConfig()->setOption('italic_style', '*');
$converter->getConfig()->setOption('bold_style', '__');
$html = '<em>Italic</em> and a <strong>bold</strong>';
$markdown = $converter->convert($html);

Line breaks are another formatting boundary. By default, `<br>` becomes two spaces followed by a newline, which matches traditional Markdown. Setting `hard_break` to `true` omits those spaces and follows GitHub Flavored Markdown. Setting it to `false` restores the documented default.

$converter = new HtmlConverter();
$html = '<p>test<br>line break</p>';
$converter->getConfig()->setOption('hard_break', true);
$markdown = $converter->convert($html);

Autolinking is configurable as well. With `use_autolinks` enabled, a link whose visible text is the URL can become `<https://thephpleague.com>`. Disabling the option uses the full `[url](url)` form. These controls affect presentation, not the safety or semantics of the original HTML.

Maintenance, Licensing, and the Alternative Workflow

The repository is not archived. Its last push was on 2026-10-10, and the release list includes versions 5.1.2, 5.1.3, and 5.1.4. The recent release history shows activity around the default `master` branch, but the README does not define a support policy for older PHP versions or a compatibility matrix beyond the PHP 7.2+ requirement. Upgrading therefore requires checking the package version against the application's PHP runtime and reviewing `CHANGELOG.md`.

The project uses the MIT license. The README links to `LICENSE`, so the repository includes the license text. This review does not interpret the legal effect of that license; it only records the declared licensing choice.

A real alternative is to keep content in Markdown from the start or sanitize HTML before conversion. HTML Purifier is mentioned by the README as an additional filtering library for untrusted input. It addresses filtering, not Markdown conversion. A separate Markdown-first workflow avoids HTML round trips but requires changing the authoring and storage model. For this library, the practical decision is whether configurable conversion is preferable to maintaining a separate content representation.

Editorial conclusion

Adopt this library when a PHP application already has HTML and needs Markdown output with controlled handling of unsupported elements. Do not treat it as a security boundary or as a general HTML parser replacement. Before adoption, verify how your input is filtered, decide whether unsupported tags should be retained, stripped, or removed with their content, and check the required PHP version against your runtime. The first integration should exercise those options with the HTML shapes your application actually receives.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. thephpleague/html-to-markdown on GitHub