README

danhunsaker/markua是一个PHP Markdown解析器，旨在支持完整的Markua规范。Markua规范仍在演变中。

目标

本项目的目标是完全支持Markua规范，并将随着规范的演变而不断发展。

League\CommonMark

此包依赖于League\CommonMark，除了使用Markua规范外，功能完全相同。

安装

本项目可以通过Composer安装。

$ composer require danhunsaker/markua

基本用法

MarkuaConverter类提供了一个将Markua转换为HTML的简单包装器。

use Danhunsaker\Markua\MarkuaConverter;

$converter = new MarkuaConverter();
echo $converter->convertToHtml('# Hello World!');

// <h1>Hello World!</h1>

高级用法与自定义

实际的转换过程需要两个步骤

1. 将Markdown输入解析为AST
2. 将AST文档渲染为HTML

虽然MarkuaConverter包装器简化了此过程，但高级用户可能会希望亲自完成此操作。

use League\CommonMark\DocParser;
use League\CommonMark\Environment;
use League\CommonMark\HtmlRenderer;
use Danhunsaker\Markua\Environment\Markua;

// Obtain a pre-configured Environment with all the Markua parsers/renderers ready-to-go
$environment = Environment::createEnvironment(new Markua());

// Optional: Add your own parsers/renderers here, if desired
// For example:  $environment->addInlineParser(new TwitterHandleParser());

// Create the document parser and HTML renderer engines
$parser = new DocParser($environment);
$htmlRenderer = new HtmlRenderer($environment);

// Here's our sample input
$markdown = '# Hello World!';

// 1. Parse the Markdown to AST
$documentAST = $parser->parse($markdown);

// Optional: If you want to access/modify the AST before rendering, do it here

// 2. Render the AST as HTML
echo $htmlRenderer->renderBlock($documentAST);

// The output should be:
// <h1>Hello World!</h1>

这种方法允许您在渲染之前访问/修改AST。

您还可以通过使用Environment类注册它们来添加自定义解析器/渲染器。league/commonmark文档提供了几个自定义示例，例如

• 解析Twitter处理为个人资料链接
• 将表情符号转换为表情图像

您还可以参考核心CommonMark解析器/渲染器，因为它们使用您可用的相同功能。

与Markua的兼容性

本项目旨在完全支持整个Markua规范。其他Markdown版本可能可以工作，但不支持。对规范所做的任何/所有更改最终都将反映在此代码库中。

此包不是Markua的一部分，而是一个兼容的衍生品。

文档

待办事项。

测试

$ ./vendor/bin/phpunit

稳定性和版本控制

虽然此包运行良好，但底层代码尚不能被视为“稳定”。原始规范可能在不久的将来发生变化，这将导致对此代码的相应更改。任何标记为@api的方法都不会改变，但其他方法/类可能会改变。

主版本1.0.0将保留在Markua和本项目都认为稳定时。0.x.x将一直使用到那时。

将严格遵守SemVer。

贡献

如果您在规范中发现错误，请将其报告给Markua项目。任何结果修复最终也将在此项目中实现。

有关更多信息，请参阅CONTRIBUTING。

致谢与认可

• Davey Shafik
• Colin O'Dell
• John MacFarlane
• 所有贡献者

许可协议

danhusaker/markua 采用 BSD-3 许可协议。更多详细信息请参阅 LICENSE 文件。