简码

Zola 从 WordPress 中借用了短代码的概念。在我们的例子中，短代码对应于目录中定义的模板templates/shortcodes，可以在 Markdown 文件中使用。

从广义上讲，Zola 的短代码涵盖两个不同的用例：

注入更复杂的 HTML：Markdown 适合编写，但当您需要添加内联 HTML 或样式时，它就不是很好了。
简化基于重复数据的任务：当您有要在页面正文中显示的外部数据时。

后者也可以通过编写 HTML 来解决，但是 Zola 允许使用.md 以.html. 如果您想在目录中包含由短代码生成的标题，这可能特别有用。

如果你想在模板中使用类似于短代码的东西，你可以使用Tera macros。它们是您可以调用以返回一些文本的函数或组件。

🔗编写简码

让我们编写一个简码来嵌入 YouTube 视频作为示例。youtube.html在目录中调用的文件中templates/shortcodes，粘贴以下内容：

<div {% if class %}class="{{class}}"{% endif %}>
    <iframe
        src="https://www.youtube.com/embed/{{id}}{% if autoplay %}?autoplay=1{% endif %}"
        webkitallowfullscreen
        mozallowfullscreen
        allowfullscreen>
    </iframe>
</div>

这个模板非常简单：一个指向 YouTube 嵌入 URL 的 iframe，包裹在一个<div>. 在输入方面，此短代码至少需要一个变量：id. 因为其他变量在if语句中，所以它们是可选的。

就是这样。youtubeZola 现在会将此模板识别为名为（文件名减去扩展名）的简码.html。

Markdown 渲染器会将一个内联 HTML 节点（例如<a>或）包装<span>到一个段落中。如果您想禁用此行为，请将您的简码包装在一个<div>.

基于 Markdown 的短代码将被视为返回的内容是页面正文的一部分。例如，如果我们创建 books.md：templates/shortcodes

{% set data = load_data(path=path) -%}
{% for book in data.books %}
### {{ book.title }}

{{ book.description | safe }}
{% endfor %}

这将创建一个短代码books，其参数path指向一个.toml文件，在该文件中加载带有标题和描述的书籍列表。它们将与被调用的文档的其余部分一起流动books。

简码在解析页面的 Markdown 之前呈现，因此它们无权访问页面的目录。因此，您也不能使用// /get_page全局get_section函数。它可能在运行时工作，因为它已被加载，但在.get_taxonomyget_taxonomy_termzola servezola build

🔗使用简码

短代码有两种：

那些不带身体的，比如上面的 YouTube 例子
那些做的，比如一个引用的样式

在这两种情况下，参数都必须命名，并且它们都将传递给模板。即使没有参数，括号也是强制性的。

最后，短代码名称（以及相应的.html文件）以及参数名称只能包含数字、字母和下划线，或者在正则表达式中[0-9A-Za-z_]。虽然理论上参数名称可以是数字，但不可能在模板中使用这样的参数。

参数值可以是五种类型之一：

字符串：用双引号、单引号或反引号括起来
布尔值：true或false
float：带小数点的数字（例如，1.2）
整数：整数或其负数对应物（例如，3）
数组：任何类型值的数组，数组除外

格式错误的值将被忽略。

两种类型的简码也将获得 apage或section变量，具体取决于它们的使用位置和config变量。这些值将覆盖传递给短代码的任何参数，因此这些变量名称不应用作短代码中的参数名称。

🔗没有正文的简码

只需调用短代码，就好像它是变量块中的 Tera 函数一样。

Here is a YouTube video:

{{ youtube(id="dQw4w9WgXcQ") }}

{{ youtube(id="dQw4w9WgXcQ", autoplay=true) }}

An inline {{ youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") }} shortcode

请注意，如果您想要一些看起来像短代码但不让 Zola 尝试呈现它的内容，您将需要使用{{/*and*/}}而不是{{and来转义它}}。

🔗带正文的简码

假设我们有以下短代码quote.html模板：

<blockquote>
    {{ body }} <br>
    -- {{ author}}
</blockquote>

我们可以像这样在我们的 Markdown 文件中使用它：

As someone said:

{% quote(author="Vincent") %}
A quote
{% end %}

短代码的主体将作为body变量自动传递到渲染上下文，并且需要换行。

🔗没有参数的简码

请注意，对于这两种情况，短代码的括号都是必需的。没有括号的短代码将呈现为纯文本，并且不会发出警告。

例如，这是如何aside定义一个没有参数的短代码aside.html：

<aside>
    {{ body }}
</aside>

我们可以像这样在我们的 Markdown 文件中使用它：

Readers can refer to the aside for more information.

{% aside() %}
An aside
{% end %}

🔗类似于简码的内容

如果你想要一些看起来像短代码的内容但 Zola 不尝试渲染它，你将需要使用{%/*and*/%}而不是{%and来转义它%}。在结束标记之前，您不需要转义任何其他内容。

🔗简码上下文

除了您作为参数显式传递的内容之外，每个短代码都可以访问一些变量。这些变量在以下小节中解释：

调用次数 ( nth)
当前语言 ( lang)，除非从markdown模板过滤器中调用（在这种情况下，它将始终与配置中的值相同default_language，或者en当它未设置时）
colocated_path

当这些变量之一与作为参数传递的变量冲突时，将使用参数值。

🔗`nth` : 调用次数

每个短代码上下文都在一个名为的变量中传递，nth该变量跟踪在当前 Markdown 文件中调用特定短代码的次数。给定一个简码true_statement.html模板：

<p id="number{{ nth }}">{{ value }} is equal to {{ nth }}.</p>

它可以在我们的 Markdown 中使用，如下所示：

{{ true_statement(value=1) }}
{{ true_statement(value=2) }}

这在为旁注或尾注等功能实现自定义标记时很有用。

🔗`lang` : 当前语言

注意：从模板过滤器中调用短代码时markdown，lang变量将始终为en. 如果您觉得需要，请考虑改用模板宏。如果你真的需要它，你可以重写你的 Markdown 内容以作为lang参数传递给短代码。

lang每个短代码都可以访问上下文变量中的当前语言。这对于根据每种语言的方式在简码中呈现/过滤信息很有用。例如，要在名为的短代码中显示当前页面的每种语言的书籍封面bookcover.md：

![Book cover in {{ lang }}](cover.{{ lang }}.png)

🔗`page`或`section`

您可以访问普通模板中等效变量的略微精简版本。以下属性将为空：

翻译
反向链接
页数

（注意：这是因为 markdown 的渲染是在填充部分之前完成的）

短代码中一个有用的属性page是colocated_path. 当您想将某些资产的名称传递给短代码而不重复完整的文件夹路径时，可以使用此方法。load_data与or组合时最有用resize_image。

{% set resized = resize_image(format="jpg", path=page.colocated_path ~ img_name, width=width, op="fit_width") %}
<img alt="{{ alt }}" src="{{ resized.url | safe }}" />

🔗例子

这里有一些灵感的简码。

🔗 YouTube

为 YouTube 视频嵌入响应式播放器。

论点是：

id：视频ID（必填）
playlist: 播放列表 ID（可选）
class<div>: 添加到iframe 周围的类
autoplay：设置为“true”时，视频会在加载时自动播放

代码：

<div {% if class %}class="{{class}}"{% endif %}>
    <iframe src="https://www.youtube-nocookie.com/embed/{{id}}{% if playlist %}?list={{playlist}}{% endif %}{% if autoplay %}?autoplay=1{% endif %}" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
</div>

使用示例：

{{ youtube(id="dCKeXuVHl1o") }}

{{ youtube(id="dCKeXuVHl1o", playlist="RDdQw4w9WgXcQ") }}

{{ youtube(id="dCKeXuVHl1o", autoplay=true) }}

{{ youtube(id="dCKeXuVHl1o", autoplay=true, class="youtube") }}

🔗图片库

有关代码和示例，请参见内容处理页面。

简码