README

支持在 Markdown 语言 中使用 Nette 框架 和模板系统 Latte。

要求

• PHP >= 8.3
• Nette >= 3.2
• Latte >= 3.0

安装

安装 interitty/markdown 的最佳方式是使用 Composer

composer require interitty/markdown

此包不直接依赖于特定的 Markdown 解析器实现。它允许使用专用适配器统一地与不同的库一起工作。当选定的选项不再适合或不可用时的当前 PHP 版本，请在配置中选取另一个合适的选项。

目前支持以下 Composer 包。可以同时选择和安装一个或多个。

composer require league/commonmark
composer require michelf/php-markdown

然后，在 Nette 配置文件 中注册扩展。

# app/config/config.neon
extensions:
    markdown: Interitty\Markdown\Nette\DI\MarkdownExtension

用法

可以在任何 Latte 模板中使用 filter 和 tag。

内联支持

Web 应用的 HTML 模板和 mock 通常包含一个预格式化的文档，其中需要添加翻译。这默认使用 {_...} 符号完成。随着时间的推移，以文本更改和高亮显示的形式进行一些小的修正。为此，提供有限的 markdown 语言 支持非常有用，这样就可以在不更改应用程序代码的情况下使用 md 过滤器或标签。

<p>{_'**Markdown** text content'|md}</p>

当然，也可以在不翻译的情况下使用此功能。

<p>{md '**Markdown** text content'}</p>

默认情况下，以下 HTML 标签在 "内联" 模式下受支持：a、abbr、b、br、cite、code、command、del、dfn、em、i、ins、kbd、mark、meter、progress、q、s、samp、small、span、strong、sub、sup、time、u、var、wbr。所有其他标签都将从结果字符串中删除。可以在配置项 allowedTagsInline 中更改允许的 HTML 标签列表。

# app/config/config.neon
markdown:
    allowedTagsInline: [b, i, u]

块支持

有时需要将整个 Markdown 文档无限制地转换。为此，有一个 "块" 模式，它具有 mdb 过滤器和标签辅助器。

{block|mdb}
## Headline

**Markdown** text content
{/block}

{capture $markdownText}
## Headline

**Markdown** text content
{/capture}

{md $markdownText}

独立使用

有时可以单独转换 Markdown 文本，而不使用模板系统。这可以通过从依赖注入容器中获取的 Interitty\Markdown\Markdown 对象来完成。

<?php

declare(strict_types=1);

namespace App\Models;

use Interitty\Markdown\Markdown;

class FooService
{
    public function __construct(
        protected Markdown $markdown
    ) {
    }

    public function processMarkdown(string $markdown): string
    {
        return $this->markdown->processMarkdown($markdown);
    }
}

配置

扩展被设计成默认情况下无需设置任何东西。当前安装的解析器用作 latte 过滤器 md。然而，在另一个标识符、不同的服务或仅支持严格的 Markdown 的情况下使用它可能是有用的。

# app/config/config.neon
markdown:
    adapter: null # Can be one of `commonMark`, `githubFlavoured`, `markdown`, `markdownExtra`, `texy` or one of `@service`
    allowedTagsInline: null # Or array of strings with allowed HTML tags for "inline" filter and tag.
    extended: true # false for strict markdown syntax only
    helper: `mdb` # Any string like `parsedown` to be compatible with previous markdown support implementation
    helperInline: `md` # Any string

事件

Markdown服务还包含可以在处理过程中修改文本输入和输出的事件。这非常有用，例如，用于Markdown适配器本身不直接支持的额外排版编辑。

可用的事件有onBeforeProcess、onAfterProcess和onAfterInlineProcess。

extensions:
    markdown: Interitty\Markdown\Nette\DI\MarkdownExtension

services:
    markdown.markdown:
        class: Interitty\Markdown\Markdown
        setup:
            - $onAfterProcess:
                - strtolower