README

由Michel Fortin编写
https://michelf.ca/

基于John Gruber的Markdown
https://daringfireball.net/

简介

这是一个包含PHP Markdown解析器和其同族的PHP Markdown Extra（具有额外功能）的库包。

Markdown是一种用于网页作家的文本到HTML转换工具。Markdown允许您使用易于阅读、易于书写的纯文本格式进行编写，然后将它转换为结构有效的XHTML（或HTML）。

"Markdown"实际上是两样东西：一种纯文本标记语法，以及一个将纯文本标记转换为HTML的软件工具，最初是用Perl编写的。PHP Markdown是John Gruber原始Markdown程序的PHP端口。

Markdown语法的完整文档
— Daring Fireball (John Gruber)
Markdown Extra语法的扩展
— Michel Fortin

需求

此库包需要PHP 7.4或更高版本。

注意：PHP Markdown和PHP Markdown Extra的较旧插件/库混合包不再维护，但将与PHP 4.0.5及更高版本兼容。

您可能需要将pcre.backtrack_limit设置得高于1,000,000（默认值），尽管默认值通常足够。

用法

要使用Composer使用此库，首先用以下命令安装它

$ composer require michelf/php-markdown

然后包含Composer生成的vendor/autoload.php以启用自动加载

require 'vendor/autoload.php';

没有Composer，为了使自动加载工作，您的项目需要一个与PSR-4或PSR-0兼容的自动加载器。有关最小自动加载器设置，请参阅包含的Readme.php文件。（如果您不能使用自动加载，请参阅以下内容。）

有类自动加载的情况

use Michelf\Markdown;
$my_html = Markdown::defaultTransform($my_text);

Markdown Extra语法也以相同的方式提供

use Michelf\MarkdownExtra;
$my_html = MarkdownExtra::defaultTransform($my_text);

如果您希望将PHP Markdown与另一个构建来解析HTML的文本过滤器函数一起使用，您应该在transform函数调用之后过滤文本。以下是一个使用PHP SmartyPants的示例

use Michelf\Markdown, Michelf\SmartyPants;
$my_html = Markdown::defaultTransform($my_text);
$my_html = SmartyPants::defaultTransform($my_html);

所有这些示例都是使用解析器类内部发现的静态defaultTransform静态函数完成的。如果您想自定义解析器配置，也可以直接实例化它并更改一些配置变量

use Michelf\MarkdownExtra;
$parser = new MarkdownExtra;
$parser->fn_id_prefix = "post22-";
$my_html = $parser->transform($my_text);

要了解更多信息，请参阅完整的配置变量列表。

没有自动加载器的用法

如果您不能使用类自动加载，您仍然可以使用include或require来访问解析器。要加载Michelf\Markdown解析器，这样做

require_once 'Michelf/Markdown.inc.php';

或者，如果您需要Michelf\MarkdownExtra解析器

require_once 'Michelf/MarkdownExtra.inc.php';

虽然纯.php文件依赖于自动加载才能正确工作，但使用.inc.php文件将积极加载在需要时才会加载的依赖项。

公共API和版本策略

版本号的形式为major.minor.patch。

PHP Markdown的公共API包括两个解析器类Markdown和MarkdownExtra、它们的构造函数、transform和defaultTransform函数以及它们的配置变量。对于给定的主版本号，公共API是稳定的。在次要版本号增加时，可能会添加一些内容。

受保护的成员不被视为公共API。 这种做法不寻常，值得解释。每次对某项内容的底层实现进行更改时都增加主版本号，将为绝大多数仅使用解析器的用户带来非必要的版本号。受保护的成员旨在创建以不同方式行为的解析器子类。很少有人创建解析器子类。我不想通过使所有内容私有来阻碍这种行为，但与此同时，如果您使用受保护的成员，我也不能保证版本之间的任何稳定钩子。

语法更改 将会增加新功能的次版本号，以及小修正的补丁号。一个 新功能 是需要更改语法文档中的内容。请注意，由于PHP Markdown Lib包括两个解析器，任何一个的语法更改都会增加次版本号。此外，请注意，与Markdown语法没有完全兼容的版本：所有输入始终有效，因此新功能总是替换之前合法的内容，尽管通常这样做没有意义。

错误

要提交错误报告，请发送电子邮件至：[email protected]

请在报告中包含以下内容：（1）示例输入；（2）您期望的输出；（3）PHP Markdown实际产生的输出。

如果您遇到Markdown给出空结果的问题，首先检查回溯限制是否太低，可以通过运行 php --info | grep pcre 来检查。有关详细信息，请参阅上面的安装和需求。

开发和测试

欢迎提交修复错误的拉取请求。拟议的新功能将在决定接受或拒绝之前进行细致的审查——考虑向后兼容性、潜在副作用和未来的可扩展性。

如果您提交的拉取请求包含对解析器的更改，请将更改的测试添加到 test/ 目录中。这可以是一个简单的 .text（输入）文件，对应一个 .xhtml（输出）文件，放置在 ./test/resources/ 下的适当类别中。

传统上测试是在单独的存储库中，MDTest，但现在它们位于这里，与源代码一起。

捐赠

如果您想进行捐赠，以帮助我投入更多时间到PHP Markdown中，请访问michelf.ca/donate。

版本历史

PHP Markdown Lib 2.0.0（2022年9月26日）

现在需要PHP版本7.4或更高。
为解析器的配置属性添加了类型注解。（感谢Tac Tacelosky。）
修复了由无效计数器变量引起的PHP 8中的TypeError。（感谢Alexey Kopytko。）
Composer包现在排除了开发文件。（感谢Cédric Anne。）

PHP Markdown Lib 1.9.1（2021年11月23日）

现在将 <details> 和 <summary> 作为块级元素处理，这样它们就不会被 <p> 包裹。（感谢Thomas Hochstein提供的修复。）
修复了在Markdown Extra中向链接添加辅助属性时意外出现的空标题属性。（感谢Richie Black提供的修复。）

PHP Markdown Lib 1.9.0（2019年12月1日）

添加了 fn_backlink_label 配置变量，用于将一些文本放入 aria-label 属性中。（感谢Sunny Walker的实现。）
在 fn_backlink_html、fn_backlink_class、fn_backlink_title 和 fn_backlink_label 中的 "^^" 出现将用HTML输出中的相应脚注编号替换。"%%" 的出现将用参考（脚注可以有多个参考）的编号替换。（感谢Sunny Walker的实现。）
添加了配置变量 omit_footnotes。当设置为 true 时，脚注不会被附加到生成的 HTML 文件的末尾，并且 footnotes_assembled 变量将包含脚注列表的 HTML，允许将脚注移动到页面上的其他位置。（感谢 James K. 的实现。）

注意：当在页面上放置 footnotes_assembled 的内容时，请考虑为包含脚注列表的 <div> 或 <section> 添加属性 role="doc-endnotes"，以便它们可以通过与默认 HTML 输出相同的方式被辅助工具访问。
修复了 PHP 关于使用花括号访问文本字符串中的字符的弃用警告。（感谢 Remi Collet 和 Frans-Willem Post。）

PHP Markdown Lib 1.8.0（2018 年 1 月 14 日）

使用 Composer 的自动加载现在使用 PSR-4。
Markdown Extra 脚注的 HTML 输出现在包括来自 WAI-ARIA 的 role 属性，使其更具可访问性。（感谢 Tobias Bengfort）
在 Markdown Extra 中添加了 hashtag_protection 配置变量。当设置为 true 时，它防止没有空格的 ATX 风格标题被解释为标题。这样就可以保留你宝贵的标签。（感谢 Jaussoin Timothée 的实现。）

PHP Markdown Lib 1.7.0（2016 年 10 月 29 日）

添加了 hard_wrap 配置变量，使文本中的所有换行符在 HTML 输出中成为 <br> 标签。默认情况下，根据 Markdown 语法标准，除非它们由两个空格 precedes，否则这些换行符将被忽略。感谢 Jonathan Cohlmeyer 的实现。
改进了列表项的解析，以修复由 hard_wrap 引入的问题。这应该不会对输出产生任何影响，除了以两个空格结尾的（因此也是换行符结尾的）行内列表项。
添加了 code_span_content_func 配置变量，它接受一个函数，该函数将代码 span 的内容转换为 HTML。这可以用于实现语法高亮。尽管与代码块等效项相反，没有指定语言的语法。归功于 styxit 的实现。
修复了 Markdown Extra 中的一个问题，其中行尾两个空格的硬换行符在 HTML 块元素（如 <p markdown="1">）内不起作用，因为这些元素期望只有行内级内容。
在解析器代码中，切换到 PHPDoc 注释格式。感谢 Robbie Averill 的帮助。

PHP Markdown Lib 1.6.0（2015 年 12 月 23 日）

注意：此版本被错误地发布为 1.5.1，日期为 12 月 22 日，这与版本政策相矛盾。

对于 Markdown Extra 中的围栏代码块，现在可以在特殊属性块之前设置代码块的类名。以前，这个类名只允许在没有特殊属性块的情况下使用。
添加了 code_block_content_func 配置变量，它接受一个函数，该函数将代码块的内容转换为 HTML。这对于语法高亮非常有用。对于 Markdown Extra 中的围栏代码块，该函数可以访问语言类名（特殊属性块之外的那个）。归功于 Mario Konrad 提供的实现。
脚注中的弧形箭头字符现在后面跟着一个 Unicode 变体选择器，以防止它在 iOS 上以表情符号形式显示。

请注意，在旧浏览器中，变体选择器通常被解释为单独的字符，这使得它出现在箭头之后。因此，现在还有一个 fn_backlink_html 配置变量，可以用来设置链接文本为其他内容。归功于 Dana 提供的实现。
修复了 MarkdownExtra 中的一个问题，其中在特殊属性块之后的较长标题行会达到回溯限制并返回空字符串。

PHP Markdown Lib 1.5.0（2015 年 3 月 1 日）

增加了功能：可以以不同于1的数字开始有序列表，并且在HTML输出中体现这一点。可以通过Markdown解析器的enhanced_ordered_lists配置变量来启用此功能；Markdown Extra默认启用。感谢Matt Gorle提供实现。
增加了在任何允许额外属性块的地方（链接、图像、标题）插入自定义HTML属性的能力。值必须是非引号，不能包含空格，并且仅限于ASCII字符的字母数字。感谢Peter Droogmans提供实现。
增加了header_id_func配置变量，它接受一个函数，可以从标题文本生成一个id属性值。感谢Evert Pot提供实现。
增加了url_filter_func配置变量，它接受一个函数，可以将任何链接或图像URL重写为不同的内容。

PHP Markdown Lib 1.4.1（2014年5月4日）

HTML块解析器现在将<figure>视为块级元素（应该是这样的），而不再将其包装在<p>中或将其内容解析为Markdown语法（尽管在Markdown Extra中，如果您希望在其中使用Markdown语法，可以使用markdown="1"）。
<style>元素的内容现在将被保留，其内容不会被视为Markdown。
修正了一个错误，其中一些带有空格的行内链接即使在括号内也不会工作。
```
[link](<s p a c e s>)
```
修复了一个问题，其中包含引号的电子邮件地址在链接属性中有时不会转义引号，导致链接损坏（以及无效的HTML）。
修复了链接定义在脚注定义之后会被脚注吞噬的情况，除非它们之间有空白行。

PHP Markdown Lib 1.4.0（2013年11月29日）

增加了对自动链接中tel: URL方案的支持。
```
<tel:+1-111-111-1111>
```
它被转换为这样（注意tel:前缀变得不可见）
```
<a href="tel:+1-111-111-1111">+1-111-111-1111</a>
```
将MarkdownExtra中从Github-Flavored Markdown中获取的回车引号围起来的代码块添加回MarkdownExtra。
增加了一个接口MarkdownInterface，由Markdown和MarkdownExtra解析器实现。如果您想为单元测试创建模拟解析器对象，可以使用该接口。
对于无法使用类自动加载的您，现在可以包含Michelf/Markdown.inc.php或Michelf/MarkdownExtra.inc.php（注意.inc.php扩展名）来自动包含解析器所需的其他文件。

PHP Markdown Lib 1.3（2013年4月11日）

这是PHP Markdown Lib的第一个版本。这个包需要PHP版本5.3或更高版本，并设计用于与PSR-0自动加载一起使用，并且可选地与Composer一起使用。以下是自PHP Markdown Extra 1.2.6以来的更改列表。

WordPress和其他系统中的插件接口不再包含在Lib包中。如果需要，经典包仍然可用：https://michelf.ca/projects/php-markdown/classic/
在Readme文件中增加了public和protected保护属性，以及有关什么是“公共API”和什么不是的章节。
更改了脚注的HTML输出：现在，脚注链接不再添加rel和rev属性，而是有类名footnote-ref，反向链接有footnote-backref。
修复了一些正则表达式，以使PCRE不会因为POSIX排序类（取决于您的PCRE版本）而发出警告。
为图像和链接添加了可选的类和id属性，其语法与标题相同。
```
[link](url){#id .class}
![img](url){#id .class}
```
这同样适用于参考样式的链接和图像。在这种情况下，您需要在参考定义处放置这些属性。
```
[link][linkref] or [linkref]
![img][linkref]

[linkref]: url "optional title" {#id .class}
```
修复了当某些表格列分隔符标记在列标题下面的分隔行中缺失时触发的PHP通知消息。
修复了一个可能导致解析器在多运行中保留与解析链接相关的无效状态的微小错误。据我所知，这种情况从未出现过，但修复它仍然值得。

版权和许可

以下条件满足的情况下，允许重新分发和使用源代码和二进制代码，无论是修改还是未修改：

源代码的重新分发必须保留上述版权声明、本条件列表和以下免责声明。
二进制形式的重新分发必须在文档和/或其他与分发一起提供的材料中复制上述版权声明、本条件列表和以下免责声明。
未经事先书面许可，不得使用 "Markdown" 或其贡献者的名称来推广或支持由此软件衍生出的产品。

本软件由版权所有者和贡献者“按原样”提供，任何明示或暗示的保证，包括但不限于适销性和特定用途适用性的暗示保证均被否认。在任何情况下，版权所有者或贡献者不应对任何直接、间接、偶然、特殊、示范性或后果性的损害（包括但不限于替代商品或服务的采购；使用、数据或利润的损失；或业务中断）承担责任，无论此类损害是由于何种原因造成的，以及基于何种责任理论，无论是在合同、严格责任还是侵权（包括疏忽或其他）中，只要这种损害与使用本软件有关，即使被告知此类损害的可能性。

michelf / php-markdown

维护者

详细信息