README

针对Twig 2.*进行了更新 - 对于Twig 1.*，请使用版本1.0.1

一个简单且可扩展的Twig扩展，用于提供Markdown过滤器、全局变量、标签和函数。

默认情况下，此扩展附带 ParsedownExtra，但可以很容易地通过实现提供的接口并传递您的新实现到扩展中，用您选择的任何Markdown处理器替换。

安装

您可以通过Composer安装此扩展包。

composer require jralph/twig-markdown

您也可以将包及其版本添加到您的composer.json文件中。

"require": {
    "jralph/twig-markdown": "dev-master"
}

使用Twig进行设置

要使用此扩展与twig（不使用任何附加功能，如Laravel的TwigBridge。 见下文。），您可以简单地做以下操作。

$twig = new Twig_Environment($loader);
$twig->addExtension(new Jralph\Twig\Markdown\Extension(
    new Jralph\Twig\Markdown\Parsedown\ParsedownExtraMarkdown
));

使用Laravel 5的TwigBridge进行设置

要使用此插件与TwigBridge，与Laravel一样简单，但有多种添加扩展的方法。

通过config/twigbridge.php

您可以直接将扩展添加到config/twigbridge.php文件中extensions数组内的enabled部分。（注意，您需要确保配置文件已发布php artisan vendor:publish，以便此文件存在。）

'extensions' => [

    'enabled' => [
        // Other TwigBridge Extensions
        new Jralph\Twig\Markdown\Extension(
            new Jralph\Twig\Markdown\Parsedown\ParsedownExtraMarkdown
        ),
    ]

]

通过Twig外观

您还可以使用TwigBridge提供的Twig外观来添加扩展。

Twig::addExtension(new Jralph\Twig\Markdown\Extension(
    new Jralph\Twig\Markdown\Parsedown\ParsedownExtraMarkdown
));

您可以在Laravel 5安装中用任何您喜欢的方式添加此代码，但我们建议使用服务提供者。

安全性

由于Markdown中的任何HTML都是完全有效的，因此此包不选择预先清理输入，只有在强制时（tag功能就是这样）才进行预先清理。

当使用与用户输入结合的filter、function或global时，应谨慎行事，因为这可能导致XSS漏洞。一般来说，您希望将<script>标签从任何输出中剥离，作为最低限度的要求。

提供的功能

Twig-Markdown扩展提供全局变量、函数、过滤器和标签，以帮助您处理Markdown。

标签（输入安全）

我们还提供了一个方便的标签，如果您想在模板中编写Markdown，可以使用它。

{% markdown %}
    # Some Markdown

    This is some simple markdown content.
    
    {{ moreMarkdown }}
{% endmarkdown %}

注意：过滤器输入会自动清理。标签不支持包含HTML的Markdown。

过滤器（输入不安全，不支持HTML）

就像使用任何其他twig过滤器一样使用。

{{ "# Some Markdown" | markdown }}
{{ markdownVariable | markdown }}

{% apply markdown %}
    # Some Markdown

    This is some simple markdown content.
    
    {{ moreMarkdown }}
{% endapply %}

注意：上述过滤器使用是不安全的。过滤器输入不会自动清理。请使用以下escape过滤器在模板中清理。

{{ markdownVariable | escape | markdown }}

函数（输入不安全，支持HTML）

就像使用任何其他twig函数一样使用。

{{ markdown("# Some Markdown") }}
{{ markdown(markdownVariable) }}

注意：上述函数使用是不安全的。函数输入不会自动清理。请使用以下escape过滤器在模板中清理。

{{ markdown(markdownVariable | escape) }}

全局（输入不安全，支持HTML）

您还可以使用全局变量直接访问MarkdownInterface合约的实现。

{% autoescape false %}
    {{ markdown.parse("# Some Markdown") }}
    {{ markdown.parse(markdownVariable) }}
{% endautoescape %}

注意使用{% autoescape false %}。如果没有这个，生成的HTML将被转义......这可能正是您想要的。如果您想转义输入，但保持HTML输出，可以像下面这样做

{% autoescape false %}
    {{ markdown.parse(markdownVariable | escape) }}
{% endautoescape %}

使用另一个处理器

想使用除了ParsedownExtra之外的处理器？没问题！

只需实现Jralph\Twig\Markdown\Contracts\MarkdownInterface接口，将其添加到扩展中，就可以使用了。

该接口要求以下方法：

parse($text);
- 此方法应返回解析后的$text。

示例使用Michelf Markdown。

// MichelfMardown.php
<?php

use Jralph\Twig\Markdown\Contracts\MarkdownInterface;
use Michelf\Markdown;

class MichelfMardown implements MarkdownInterface {

    public function parse($text)
    {
        $markdown = new Markdown;

        return $markdown->transform($text);
    }

}

现在你已经设置了实现，只需将其添加到twig扩展中。

// For plain twig.

$twig = new Twig_Environment($loader);
$twig->addExtension(new Jralph\Twig\Markdown\Extension(
    new MichelfMardown
));

// For TwigBridge

'extensions' => [

    'enabled' => [
        // Other TwigBridge Extensions
        new Jralph\Twig\Markdown\Extension(
            new MichelfMardown
        ),
    ]

]

// OR

Twig::addExtension(new Jralph\Twig\Markdown\Extension(
    new MichelfMardown
));

就这么简单！

贡献/维护

我会尽最大努力保持此包的最新状态，但如果您发现任何错误或想要添加功能，请随时在GitHub上提交问题或提交包含更改的拉取请求。

jralph / twig-markdown

维护者

详细信息