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"

样式选项

默认情况下，使用星号语法将加粗标签转换为 Markdown，并使用下划线语法将斜体标签转换为 Markdown。可以通过使用 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__"

换行选项

默认情况下，根据传统Markdown的规则，br标签会被转换成两个空格后跟一个换行符。要将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语法的组成部分，因此默认情况下不启用对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的默认样式。如果您更喜欢ATX样式（例如，# Header 1和## Header 2），则在实例化对象时，在选项数组中将header_style设置为'atx'。

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

  H3优先级及以下标题始终使用ATX样式。

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

• 引用块不自动换行——这样做可以使转换后的Markdown更容易编辑。

依赖项

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

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

贡献者

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

工作原理

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

待办事项

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

尝试将Markdown转换为HTML？

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

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

关于Elvish没有保证。