README

PHP5.4 的 Markdown 解析器，完全可扩展。Ciconia 是扩展集合，因此您可以替换、添加或删除每个解析机制。

试用演示 / 文档 / 支持的语法 / API 参考

• 基于 John Gruber 的 Markdown.pl

• 支持 (默认禁用) Github Flavored Markdown

  • 单词中的多个下划线
  • 新行
  • 代码块
  • 任务列表
  • 表格
  • URL 自动链接

• 与 karlcow/markdown-testsuite 测试

需求

• PHP5.4+
• Composer

安装

创建一个 composer.json

{
    "require": {
        "kzykhys/ciconia": "~1.0.0"
    }
}

并运行

php composer.phar install

用法

传统 Markdown

use Ciconia\Ciconia;

$ciconia = new Ciconia();
$html = $ciconia->render('Markdown is **awesome**');

// <p>Markdown is <em>awesome</em></p>

Github Flavored Markdown

要激活 6 个 gfm 功能

use Ciconia\Ciconia;
use Ciconia\Extension\Gfm;

$ciconia = new Ciconia();
$ciconia->addExtension(new Gfm\FencedCodeBlockExtension());
$ciconia->addExtension(new Gfm\TaskListExtension());
$ciconia->addExtension(new Gfm\InlineStyleExtension());
$ciconia->addExtension(new Gfm\WhiteSpaceExtension());
$ciconia->addExtension(new Gfm\TableExtension());
$ciconia->addExtension(new Gfm\UrlAutoLinkExtension());

$html = $ciconia->render('Markdown is **awesome**');

// <p>Markdown is <em>awesome</em></p>

选项

use Ciconia\Ciconia;

$ciconia = new Ciconia();
$html = $ciconia->render(
    'Markdown is **awesome**',
    ['tabWidth' => 8, 'nestedTagLevel' => 5, 'strict' => true]
);

渲染 HTML 或 XHTML

Ciconia 默认渲染 HTML。如果您更倾向于 XHTML

use Ciconia\Ciconia;
use Ciconia\Renderer\XhtmlRenderer;

$ciconia = new Ciconia(new XhtmlRenderer());
$html = $ciconia->render('Markdown is **awesome**');

// <p>Markdown is <em>awesome</em></p>

扩展 Ciconia

如何扩展

创建扩展很简单，只需实现 Ciconia\Extension\ExtensionInterface。

您的类必须实现 2 个方法。

void register(Ciconia\Markdown $markdown)

将您的回调注册到 Markdown 事件管理器。 Ciconia\Markdown 是 Ciconia\Event\EmitterInterface 的实例（类似于 Node.js 的 EventEmitter）

string getName()

返回您的扩展名称。如果您的名称与核心扩展之一相同，则将被您的扩展替换。

扩展示例

此示例扩展将 @username 提及转换为链接。

<?php

use Ciconia\Common\Text;
use Ciconia\Extension\ExtensionInterface;

class MentionExtension implements ExtensionInterface
{

    /**
     * {@inheritdoc}
     */
    public function register(\Ciconia\Markdown $markdown)
    {
        $markdown->on('inline', [$this, 'processMentions']);
    }

    /**
     * @param Text $text
     */
    public function processMentions(Text $text)
    {
        // Turn @username into [@username](http://example.com/user/username)
        $text->replace('/(?:^|[^a-zA-Z0-9.])@([A-Za-z]+[A-Za-z0-9]+)/', function (Text $w, Text $username) {
            return '[@' . $username . '](http://example.com/user/' . $username . ')';
        });
    }

    /**
     * {@inheritdoc}
     */
    public function getName()
    {
        return 'mention';
    }
}

注册您的扩展。

<?php

require __DIR__ . '/vendor/autoload.php';

$ciconia = new \Ciconia\Ciconia();
$ciconia->addExtension(new MentionExtension());
echo $ciconia->render('@kzykhys my email address is example@example.com!');

输出

<p><a href="http://example.com/user/kzykhys">@kzykhys</a> my email address is example@example.com!</p>

每个扩展将字符串作为 Text 对象处理。请参阅 kzykhys/Text 的 API 部分。

事件

可能的事件有

查看扩展的源代码

查看事件和计时信息

创建您自己的渲染器

Ciconia 支持 HTML/XHTML 输出。但如果你喜欢自定义输出，只需创建一个实现 Ciconia\Renderer\RendererInterface 的类。

查看 Ciconia\Renderer\RendererInterface

命令行界面

用法

基本用法：（将结果输出到 STDOUT）

ciconia /path/to/file.md

以下命令将结果保存到文件

ciconia /path/to/file.md > /path/to/file.html

或使用管道（在 Windows 上不起作用）

echo "Markdown is **awesome**" | ciconia

命令行选项

 --gfm                 Activate Gfm extensions
 --compress (-c)       Remove whitespace between HTML tags
 --format (-f)         Output format (html|xhtml) (default: "html")
 --lint (-l)           Syntax check only (lint)

脚本在哪里？

CLI 脚本默认安装到 vendor/bin/ciconia。要更改位置

是的，有两种方式可以指定替代的 vendor 二进制位置

1. 在 composer.json 中设置 bin-dir 配置设置
2. 设置环境变量 COMPOSER_BIN_DIR

https://getcomposer.org.cn/doc/articles/vendor-binaries.md

使用 PHAR 版本

您还可以使用 单个 phar 文件

ciconia.phar /path/to/file.md

如果您希望全局访问此命令，请下载 ciconia.phar 并将其移动到您的 PATH 中。

mv ciconia.phar /usr/local/bin/ciconia

测试

安装或更新 dev 依赖。

php composer.phar update --dev

然后运行 phpunit

许可证

MIT 许可证

贡献

请随意 Fork 这个仓库并发送拉取请求。 (贡献者列表)

作者

Kazuyuki Hayashi (@kzykhys)