html-to-markdown: 用PHP转换HTML到Markdown
( 如需查看英文版本,请 点击这里 )
HTML到Markdownfor PHP
库,用于将HTML转换为Markdown,以确保您的正常性和方便性。
要求:PHP5.3+或PHP7.0+
首席开发者:@colinodell
@原作者:尼克尼斯
为什么要将HTML转换成Markdown?
“这是什么炼金术?”你喃喃自语。”我能理解为什么要将Markdown转换为HTML,“你继续说,已经有些费劲了,”但为什么要走另一条路呢
通常,如果:
- 您有一个现有的HTML文档,需要由有品位的人编辑。
- 您希望以HTML格式存储新内容,但将其编辑为Markdown。
- 您想将HTML电子邮件转换为纯文本电子邮件。
- 你知道有个人多年来一直在把HTML转换成Markdown,现在他能说精灵语了。你很想说精灵语。
- 你真的很喜欢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转换表单以供尝试。
Conversion options
默认情况下,htmltoMarkdown保留HTML标记,而不使用Markdown等价物,如<span>
和<div>
。
要去掉没有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
中传递space-separated标记列表,如下所示:
$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! -->"
Style options
默认情况下,粗体标记使用星号语法转换,斜体标记使用下划线语法转换。使用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转换为两个空格,后跟一个换行符。根据GitHub口味的Markdown(GFM),将hard_break
设置为true
,以省略这两个空格。
$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"
Autolinking options
默认情况下,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://google.com](https://google.com)"
传递自定义环境对象
您可以传递currentEnvironment
对象来定制,即应该使用哪些转换器。
$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="" />"
Limitations
- MarkdownExtra、MultiMarkdown和其他变体不受支持–只支持Markdown。
Known issues
- 嵌套列表和包含多个段落的列表未正确转换。
- 块引号内的列表未正确转换。
- 任何报告的公开问题。
在此处报告您的问题或请求功能。修补程序或测试失败的问题尤其受欢迎。
Style notes
- Setext(带下划线)标题是H1和H2的默认值。如果您更喜欢H1和H2(#Header 1和##Header 2)的ATX样式,请在实例化对象时在options数组中将
header_style
设置为“ATX”:$converter = new HtmlConverter(array('header_style'=>'atx'));
优先级为H3及更低的头始终使用ATX样式。 - 链接和图像被内联引用。不使用脚注引用(在脚注中列出了image src和anchor href属性)。
- 块引号不是行换行的,它使转换后的Markdown更易于编辑。
Dependencies
HTML到Markdown需要PHP的xml、lib-xml和dom扩展,所有这些在大多数发行版上都是默认启用的。
在诸如CentOS这样禁用PHP xml扩展的发行版上,诸如“Fatal error:Class'DOMDocument'notfound”之类的错误可以通过安装php-xml来解决。
Contributors
非常感谢到目前为止所有的贡献者。进一步的改进和功能建议是非常欢迎的。
工作原理
HTML ToMarkdown从提供的HTML创建一个DOMDocument,遍历树,并将每个节点转换为一个包含等价的markdown的文本节点,从最深嵌套的节点开始,向内到根节点。
To-do
- 支持嵌套列表和blockquotes中的列表。
- 如果标记包含不能用Markdown(例如
style
)表示的属性,则提供一个将标记保留为HTML的选项。
正在尝试将Markdown转换为HTML?
使用这些伟大的库之一:
- league/commonmark (recommended)
- cebe/markdown
- PHP Markdown
- Parsedown
不过,不能保证精灵。