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 = true 以启用 HTML5 输出而不是 HTML4。

当你使用 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 编码。其他编码目前尚未测试。

使用原始 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 Yii 2 user
$parser->rawHtmlFilter = function($input) {
    return \yii\helpers\HtmlPurifier::process($input);
};

如你所见，在示例中，rawHtmlFilter 应该是一个可调用对象，它接受可能未清理的 html 文本字符串并输出其清理后的版本。

命令行脚本

你可以使用它将 wiki 文本转换为 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 联系我。

zazza / creole

维护者

详情