README

文章解决了一个非常具体的问题：在矩阵字段中解析Markdown格式的内容。特别是包含脚注的Markdown格式内容。

你可能想知道为什么那需要一个插件。

实际上，并不需要。你可以通过仔细组合Twig宏、包含、尖叫和绝望来达到相同的结果。文章只是更简单。

要求

文章使用Smartdown来渲染你的Markdown格式内容。你必须安装并激活版本3.0.1或更高版本。

安装

文章不能通过Craft插件商店获取，可能永远不会。如果你认为文章对你的Craft项目有用，你可以使用Composer来安装它。

$ cd /path/to/site
$ composer require experience/article

配置

文章对您的矩阵字段结构或用于渲染内容的模板没有假设。

您只需要通过配置插件设置页面上的“模板路径”来告诉文章在哪里找到您的模板。

使用

使用文章有三种方式

• 作为Craft服务
• 作为Craft模板服务（或现在所称的任何模板变量）
• 作为Twig过滤器

服务

文章服务公开一个名为render的方法。该方法接受一个矩阵字段，并返回解析后的内容。

use experience\article\Article;

$content = Article::getInstance()->article->render($entry->matrixField);

模板服务

文章模板服务公开与主服务相同的render方法。

{{ craft.article.render(entry.matrixField)|raw }}

请注意，您必须使用raw过滤器，否则Twig会自动转义任何HTML标签。

Twig过滤器

文章公开一个名为renderArticle的Twig过滤器。

{{ entry.matrixField|renderArticle|raw }}

与模板服务一样，不要忘记使用raw过滤器。

模板

概述

在解析矩阵字段时，文章将使用您的模板目录中的模板来渲染每个矩阵块的内容。

简而言之，文章会寻找与矩阵块handle相同的文件名。

例如，假设您的模板目录是articles/_blocks，并且您的矩阵块有一个handle为"text"。

在这种情况下，文章将寻找以下模板。如果其中一个存在，它将使用它来渲染矩阵块

• articles/_blocks/text.html
• articles/_blocks/text.twig

支持的模板扩展由Craft的defaultTemplateExtensions配置设置控制，具体请参考Craft的默认模板扩展配置设置。

block模板变量

每个模板都可以访问一个唯一的变量block，它代表当前块的MatrixBlock模型。例如，如果你的text块类型包含一个body字段，你可以按照以下方式访问它

{{ block.body }}

技巧和窍门

文章并非心灵感应者，它不会对你的模板内容做任何假设。

本节包含了一些技巧和窍门，应该会使得编写符合文章要求的模板变得更容易。

使用raw过滤器

按照以下方式对Markdown格式的内容应用raw过滤器

{{ block.markdownField|raw }}

如果不应用raw过滤器，Twig会尽力将你精心制作的Markdown转换为HTML实体，导致Markdown链接、引号等无法解析。

应用raw过滤器是一个简单的解决方案，可以节省你无数烦恼。

告诉文章HTML中是否包含Markdown

如果你将Markdown格式的内容包裹在HTML标签中，你需要让文章（更准确地说，是PHP Markdown Extra）知道。

你可以通过在包裹标签中添加markdown="1"属性来实现这一点。

<div class="content-block" markdown="1">
This text is _italic_, and wrapped in paragraph tags.
</div>

PHP Markdown Extra会自动移除markdown="1"属性，确保你的HTML保持整洁。

消除空白字符

Markdown对空白字符非常敏感。如果你突然发现内容中充斥着不需要的代码块，很可能是因为前导空白字符导致的。

以下是解决方法

<div markdown="1">
    {{- block.markdownField -}}
</div>

如果你想要了解更多信息，Twig的文档包含有关空白字符控制的详细信息。