softark/creole

基于 cebe/markdown 扩展的 PHP Creole Wiki 解析器

1.3.0.2 2023-12-21 12:50 UTC

This package is auto-updated.

Last update: 2024-08-31 00:26:18 UTC


README

Build Status Code Coverage Scrutinizer Code Quality

这是什么?

这是一个基于 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许可证许可。这意味着只要提及我的名字并包含许可文件,您就可以随心所欲地使用它。有关详细信息,请参阅许可证

联系方式

您可以通过 电子邮件twitter 联系我。