README

PHP Markdown Lib 1.7.0 - 2016年10月29日

作者：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 5.3 或更高版本。

注意：PHP Markdown 和 PHP Markdown Extra 的较旧插件/库混合包仍在维护中，并支持 PHP 4.0.5 及更高版本。

在 PHP 5.3.7 之前，pcre.backtrack_limit 默认为 100,000，在很多情况下都太小。您可能需要将其设置为更高的值。后来的 PHP 版本默认为 1,000,000，这通常足够。

用法

此库包旨在与类自动加载一起使用。为了使自动加载正常工作，您的项目需要设置一个与 PSR-0 兼容的自动加载器。请参阅包含的 Readme.php 文件以获取最小自动加载器设置。（如果您无法使用自动加载，请参阅以下内容。）

设置了类自动加载后，将 'Michelf' 文件夹放在您的包含路径中应该就足够了

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][psp] 的示例

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 和版本策略

版本号的形式为 主版本号.次版本号.修补版本号。

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

受保护的成员不被视为公共API。 这是不寻常的，需要解释。每次底层实现发生变化时，增加主版本号将给大多数仅使用解析器的人带来非必要的版本号。受保护的成员旨在创建以不同方式行为的解析器子类。很少有人创建解析器子类。我不想通过使一切私有来阻碍这种做法，但与此同时，如果您使用受保护的成员，我无法保证版本之间的任何稳定钩子。

语法更改 将增加小版本号以添加新功能，以及增加补丁号以进行小修正。一个 新功能 是需要更改语法文档中的内容。请注意，由于PHP Markdown Lib包括两个解析器，因此对其中任何一个的语法更改都将增加小版本号。此外，请注意，Markdown语法没有完美向后兼容的内容：所有输入始终有效，因此新功能始终替换了之前合法但通常没有意义的内容。

错误

请将错误报告发送至电子邮件： michel.fortin@michelf.ca

请随报告一同包含：（1）示例输入；（2）您期望的输出；（3）PHP Markdown实际产生的输出。

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

开发和测试

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

如果您提交的请求包括对解析器的更改，请为所更改的内容添加测试到 MDTest 并也提交一个请求。

捐赠

如果您希望捐赠以帮助我将更多时间投入到PHP Markdown中，请访问 michelf.ca/donate 或发送比特币到 1HiuX34czvVPPdhXbUAsAu7pZcesniDCGH。

版本历史

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

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

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

注意：此版本错误地发布为1.5.1，这与版本策略相矛盾。

在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语法（尽管在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。
添加了一个名为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和其他系统的插件接口不再包含在库包中。如果您需要，经典包仍然可用：[https://michelf.ca/projects/php-markdown/classic/](https://michelf.ca/projects/php-markdown/classic/)（注意：rel="nofollow noindex noopener external ugc" 属性）
在Readme文件中添加了 public 和 protected 保护属性，以及关于“公共API”和不是“公共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”或其贡献者的名字来认可或推广由本软件派生的产品。

websharks / php-markdown

维护者

详情