thephpleague/html-to-markdown

The primary way to use the library is to instantiate League\HTMLToMarkdown\HtmlConverter and call its convert() method with your HTML string.

use League\HTMLToMarkdown\HtmlConverter;

$converter = new HtmlConverter();

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

echo $markdown; // ==> ### Quick, to the Batpoles!

To use this library in your PHP project, install it using Composer. This library requires PHP 7.2 or higher and the xml, lib-xml, and dom PHP extensions.

composer require league/html-to-markdown

By default, the library preserves HTML tags that do not have Markdown equivalents (e.g., <span>, <div>). For security when parsing untrusted input, you can configure the converter to strip these tags or remove specific nodes entirely.

• strip_tags: When set to true, tags without Markdown equivalents are removed, but the content inside them is preserved.
• remove_nodes: Accepts a space-separated list of tags. When a tag is matched, both the tag and its content are removed.
• preserve_comments: By default, comments are stripped. Set to true to keep them, or pass an array of strings to preserve only specific comments.

Adjust how the converter handles line breaks and links.

• hard_break: Controls <br> tag conversion. If true, it uses GFM style (newline only). If false (default), it uses traditional Markdown (two spaces followed by a newline).
• use_autolinks: Controls <a> tag conversion. If true, URLs without text are converted to <url> syntax. If false (default), they are converted to the full [url](url) syntax.

You can customize the Markdown syntax used for emphasis and headers.

• bold_style: Sets the character used for bold (default is *).
• italic_style: Sets the character used for italics (default is _).
• header_style: Controls the header type. Use 'atx' for # Header style. The default is Setext (underlined) for H1 and H2. H3 and lower always use ATX style.

Table support is not enabled by default. To support HTML tables, you must explicitly add the TableConverter to the converter's environment.

use League\HTMLToMarkdown\HtmlConverter;
use League\HTMLToMarkdown\Converter\TableConverter;

$converter = new HtmlConverter();
$converter->getEnvironment()->addConverter(new TableConverter());

$html = "<table><tr<th>A</th></tr><tr<td>a</td></tr></table>";
$markdown = $converter->convert($html);

You can pass a custom Environment object to the HtmlConverter constructor. This allows you to pre-configure the environment or manually add specific converters (like TableConverter or custom ones) before instantiation.

use League\HTMLToMarkdown\HtmlConverter;
use League\HTMLToMarkdown\Environment;
use League\HTMLToMarkdown\Converter\HeaderConverter;

$environment = new Environment(array(
    // your configuration here
));
$environment->addConverter(new HeaderConverter());

$converter = new HtmlConverter($environment);

When converting HTML headers (<h1> through <h6>), you can choose between two Markdown styles using the header_style configuration option:

• atx: Uses the standard # prefix (e.g., # Header). This is the default style.
• setext: Uses underlines (e.g., Header followed by === or ---).

Note that setext style is only applied to <h1> and <h2> tags, and only if they are not descendants of a <blockquote> element. All other header levels or nested headers will default to atx style.

When an <a> tag lacks an href attribute, the converter's behavior is determined by the strip_placeholder_links configuration option.

• If strip_placeholder_links is set to true: The link is stripped, and only the link text is returned.
• If strip_placeholder_links is false (or not set): The converter returns the decoded HTML content of the element's children.

The CommentConverter allows you to control whether HTML comments are preserved in the resulting Markdown output. This is managed via the preserve_comments option in the Configuration object.

You can configure this in two ways:

1. Boolean (true): Preserves all HTML comments found in the source.
2. Array of strings: Only preserves comments whose trimmed content exactly matches one of the strings in the provided array.

If the option is false (the default) or not set, all comments are stripped from the output.

When converting HTML tables to Markdown, you can control how captions are positioned and how pipe characters (|) within cell content are handled using the following configuration options:

Table Caption Side

Controls where the <caption> content appears relative to the table. Supported values:

• top: Places the caption above the table.
• bottom: Places the caption below the table.

Table Pipe Escape

Determines how to escape the pipe character (|) inside table cells to prevent breaking the Markdown table structure. This option accepts a string representing the escape sequence. If not provided, it defaults to \|.