README

一个将 HTML 转换为 Markdown 的库，以方便您使用。

要求: PHP 7.2+

主要开发者: @colinodell

原作者: @nickcernis

为什么将 HTML 转换为 Markdown？

"这是什么魔法？" 你喃喃自语。 "我可以理解为什么要将 Markdown 转换为 HTML，" 你继续说，已经有些疲惫地提出了问题，"但为什么要反过来呢？"

通常，如果您需要将 HTML 转换为 Markdown，可能是以下原因：

1. 您有一个需要由有品味的人编辑的现有 HTML 文档。
2. 您想以 HTML 格式存储新内容，但要以 Markdown 格式编辑。
3. 您想将 HTML 邮件转换为纯文本邮件。
4. 您认识一个人，他已经将 HTML 转换为 Markdown 好多年了，现在他可以说精灵语了。您很希望能学会说精灵语。
5. 您只是真的喜欢 Markdown。

如何使用它

通过执行此命令来安装库

composer require league/html-to-markdown

将 require 'vendor/autoload.php'; 添加到脚本的顶部。

接下来，创建一个新的 HtmlConverter 实例，将您的有效 HTML 代码传递给其 convert() 函数

use League\HTMLToMarkdown\HtmlConverter;

$converter = new HtmlConverter();

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

现在，$markdown 变量包含了您的 HTML 的 Markdown 版本，作为一个字符串

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

包含的 demo 目录包含一个 HTML->Markdown 转换表单以进行测试。

转换选项

注意

默认情况下，此库保留没有 Markdown 等价的 HTML 标签，如 <span>、<div>、<iframe>、<script> 等。如果您将解析来自用户的未经验证的输入，请考虑设置以下文档中记录的 strip_tags 和/或 remove_nodes 选项，并使用库（如 HTML Purifier）提供额外的 HTML 过滤。

要删除没有 Markdown 等价的 HTML 标签，同时保留它们内部的内容，将 strip_tags 设置为 true，如下所示

$converter = new HtmlConverter(array('strip_tags' => true));

$html = '<span>Turnips!</span>';
$markdown = $converter->convert($html); // $markdown now contains "Turnips!"

或更明确地，如下所示

$converter = new HtmlConverter();
$converter->getConfig()->setOption('strip_tags', true);

$html = '<span>Turnips!</span>';
$markdown = $converter->convert($html); // $markdown now contains "Turnips!"

请注意，仅删除标签本身，而不是它们包含的内容。

要删除标签及其内容，通过 remove_nodes 传递一个空格分隔的标签列表，如下所示

$converter = new HtmlConverter(array('remove_nodes' => 'span div'));

$html = '<span>Turnips!</span><div>Monkeys!</div>';
$markdown = $converter->convert($html); // $markdown now contains ""

默认情况下，所有注释都会从内容中删除。要保留它们，使用 preserve_comments 选项，如下所示

$converter = new HtmlConverter(array('preserve_comments' => true));

$html = '<span>Turnips!</span><!-- Monkeys! -->';
$markdown = $converter->convert($html); // $markdown now contains "Turnips!<!-- Monkeys! -->"

要只保留特定注释，将 preserve_comments 设置为字符串数组，如下所示

$converter = new HtmlConverter(array('preserve_comments' => array('Eggs!')));

$html = '<span>Turnips!</span><!-- Monkeys! --><!-- Eggs! -->';
$markdown = $converter->convert($html); // $markdown now contains "Turnips!<!-- Eggs! -->"

默认情况下，占位符链接会被保留。要删除占位符链接，使用 strip_placeholder_links 选项，如下所示

$converter = new HtmlConverter(array('strip_placeholder_links' => true));

$html = '<a>Github</a>';
$markdown = $converter->convert($html); // $markdown now contains "Github"

样式选项

默认情况下，使用星号语法转换加粗标签，使用下划线语法转换斜体标签。可以通过使用 bold_style 和 italic_style 选项来更改这些。

$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); // $markdown now contains "*Italic* and a __bold__"

换行选项

默认情况下，br 标签转换为两个空格后跟换行符，如传统 Markdown 所述。将 hard_break 设置为 true 以省略两个空格，如 GitHub Flavored Markdown (GFM) 所述。

$converter = new HtmlConverter();
$html = '<p>test<br>line break</p>';

$converter->getConfig()->setOption('hard_break', true);
$markdown = $converter->convert($html); // $markdown now contains "test\nline break"

$converter->getConfig()->setOption('hard_break', false); // default
$markdown = $converter->convert($html); // $markdown now contains "test  \nline break"

自动链接选项

默认情况下，a 标签转换为最简单的链接语法，即如果没有文本或标题，则使用 <url> 语法而不是完整的 [url](url) 语法。将 use_autolinks 设置为 false 以更改此行为，始终使用完整的链接语法。

$converter = new HtmlConverter();
$html = '<p><a href="https://thephpleague.com">https://thephpleague.com</a></p>';

$converter->getConfig()->setOption('use_autolinks', true);
$markdown = $converter->convert($html); // $markdown now contains "<https://thephpleague.com>"

$converter->getConfig()->setOption('use_autolinks', false); // default
$markdown = $converter->convert($html); // $markdown now contains "[https://thephpleague.com](https://thephpleague.com)"

传递自定义环境对象

您可以将当前的 Environment 对象传递以自定义，例如使用哪些转换器。

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

$converter = new HtmlConverter($environment);

$html = '<h3>Header</h3>
<img src="" />
';
$markdown = $converter->convert($html); // $markdown now contains "### Header" and "<img src="" />"

表格支持

默认情况下不支持 Markdown 表格，因为它不是原始 Markdown 语法的组成部分。要使用表格，请显式添加转换器。

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);

限制

• 不支持 Markdown Extra、MultiMarkdown 和其他变体 - 只支持 Markdown。

样式说明

• Setext（下划线）标题是 H1 和 H2 的默认样式。如果您更喜欢 H1 和 H2 的 ATX 风格（# 标题 1 和 ## 标题 2），则在实例化对象时，在选项数组中将 header_style 设置为 'atx'。

  $converter = new HtmlConverter(array('header_style' => 'atx'));

  H3 级别和更低级别的标题始终使用 atx 风格。

• 链接和图片是内联引用的。脚注引用（其中图像源和锚点 href 属性列在脚注中）不使用。

• 引用块不自动换行 - 这使得转换后的 Markdown 更容易编辑。

依赖关系

HTML To Markdown 需要 PHP 的 xml、lib-xml 和 dom 扩展，这些扩展在大多数发行版中默认启用。

在禁用了 PHP xml 扩展的发行版（如 CentOS）上，如 "致命错误：未找到类 'DOMDocument'" 之类的错误可以通过安装 php-xml 来解决。

贡献者

非常感谢迄今为止的所有 贡献者。欢迎进一步改进和功能建议。

工作原理

HTML To Markdown 从提供的 HTML 创建 DOMDocument，遍历树，并将每个节点转换为包含等效 Markdown 的文本节点，从最深层嵌套的节点开始，逐步向根节点转换。

待办事项

• 支持嵌套列表和引用块内的列表。
• 提供选项以保留包含无法用 Markdown 表示的属性（例如 style）的标签作为 HTML。

尝试将 Markdown 转换为 HTML 吗？

使用以下这些优秀的库之一

• league/commonmark（推荐）
• cebe/markdown
• PHP Markdown
• Parsedown

不过，对于 Elvish 没有任何保证。