softark / creole
基于 cebe/markdown 扩展的 PHP Creole Wiki 解析器
Requires
- php: >=5.4.0
- lib-pcre: *
- cebe/markdown: ~1.2.0
Requires (Dev)
- ezyang/htmlpurifier: 4.6.*
- facebook/xhprof: *@dev
- phpunit/phpunit: 4.1.*
README
这是什么?
这是一个基于 Creole Wiki 的 PHP 解析器,它是基于 cebe/markdown parser for PHP 开发的。
安装
要使用它,需要 PHP 5.4 或更高版本。它也可以在 facebook 的 hhvm 上运行。
建议通过运行 composer 来安装
composer require softark/creole "~1.2"
或者,您可以将以下内容手动添加到您的 composer.json
文件的 require
部分
"softark/creole": "~1.2"
之后运行 composer update
。
请注意,安装会自动包含依赖包,特别是 "cebe/markdown",以便 creole 解析器能够正常工作。
使用方法
creole 解析器的使用方式与 cebe/markdown 解析器类似。
在您的 PHP 项目中
要解析您的 wiki 文本,您只需要两行代码。第一行是创建 creole 解析器实例
$parser = new \softark\creole\Creole();
下一步是调用 parse()
方法来解析文本,使用完整的 wiki 语言,或者调用 parseParagraph()
方法来仅解析内联元素
$parser = new \softark\creole\Creole(); $outputHtml = $parser->parse($wikiText); // parse only inline elements (useful for one-line descriptions) $parser = new \softark\creole\Creole(); $outputHtml = $parser->parseParagraph($wikiText);
您可以在解析器对象上设置以下选项(可选)
$parser->html5 = false
以启用 HTML4 输出而不是 HTML5。
当您使用 wiki 风格的链接时,即 [[link]] 用于内部链接和 [[WikiName:link]] 用于外部链接时,您应该设置以下属性
$parser->wikiUrl = 'http://www.example.com/wiki/'
为当前 wiki 的 url。$parser->externalWikis = ['Wiki-A' => 'http://www.wiki-a.com/', 'Wiki-B' => 'http://www.wiki-b.net/']
为外部 wiki。它应该是一个数组,其键是 wiki 的名称,值是它们的 url。
建议对输入字符串使用 UTF-8 编码。目前尚未测试其他编码。
使用 markdown 样式的单元格文本对齐
在 1.3.0 版本及以后,您可以选择使用 markdown 中的单元格文本对齐语法。如果您使用 markdown 表格语法编写表格源文本的 2 行,则单元格文本对齐将被渲染。如果第 2 行不符合 markdown 规范,则不会发生任何操作。
请注意,此功能仅向 td 标签添加一些类,如下所示
<tr>
<td>1st col</td>
<td class="left">2nd col</td>
<td class="right">3rd col</td>
<td class="center">4th col</td>
</tr>
在上面的例子中,第 2 列的文本应该左对齐,第 3 列右对齐,第 4 列居中对齐。如果您未能为这些类提供适当的样式,则不会发生任何操作。
因此,请记住提供适当的样式表,如下所示
td.left { text-align: left }
td.right { text-align: right }
td.center { text-align: center }
使用原始 html 块
在 1.2.0 版本及以后,您可以选择在源 wiki 文本中包含原始 html 块,尽管此功能默认禁用,因为它不在 Creole 1.0 规范中。
您可以通过指定以下选项来启用此功能
$parser->useRawHtml = true
原始 html 块应以只包含 <<<
的行开始,并以相应的结束行结束,该结束行应该是 >>>
,例如
<<<
<p>This is a raw html block.</p>
<ul>
<li>You can do whatever you want.</li>
<li>You have to be responsible for the consequence.</li>
</ul>
>>>
请注意,当指定时,原始HTML块的输出会自动使用 $parser->rawHtmlFilter
进行 清理。建议使用HTML Purifier作为过滤器。例如
$parser->rawHtmlFilter = function($input) {
$config = \HTMLPurifier_Config::createDefault();
$purifier = \HTMLPurifier::getInstance($config);
return $purifier->purify($input);
};
// Or, if you are using Yii 2
$parser->rawHtmlFilter = function($input) {
return \yii\helpers\HtmlPurifier::process($input);
};
如您在示例中看到的那样,rawHtmlFilter
应该是一个可调用的函数,它接受可能不干净的HTML文本字符串,并输出其清理后的版本。
命令行脚本
您可以使用它将维基文本转换为HTML文件
bin/creole some.txt > some.html
以下是运行 bin/creole --help
时将看到的完整帮助输出
PHP Creole to HTML converter
----------------------------
by Nobuo Kihara <softark@gmail.com>
Usage:
bin/creole [--full] [file.txt]
--full ouput a full HTML page with head and body. If not given, only the parsed markdown will be output.
--help shows this usage information.
If no file is specified input will be read from STDIN.
Examples:
Render a file with original creole:
bin/creole README.txt > README.html
Convert the original creole description to html using STDIN:
curl http://www.wikicreole.org/attach/Creole1.0TestCases/creole1.0test.txt | $cmd > creole.html
致谢
我要感谢 @cebe 创建了 cebe/markdown 库,本工作依赖于该库。
正如其名所示,cebe/markdown 是一个markdown解析器,但同时也是设计精良的通用标记语言解析器,在底层可以实现解析器,不仅适用于不同“风味”的markdown,还适用于不同的标记语言,例如Creole。
常见问题解答
我在哪里报告错误或渲染问题?
只需在github上 提交一个问题,发布您的creole代码,并描述问题。您还可以附加渲染HTML结果的截图来描述您的问题。
我可以自由使用这个吗?
此库为开源软件,并受MIT许可证许可。这意味着只要提及我的名字并包含许可文件,您就可以随心所欲地使用它。有关详细信息,请参阅许可证。