概述

Zola 使用Tera模板引擎，这与 Jinja2、Liquid 和 Twig 非常相似。

由于本文档只会讨论模板在 Zola 中的工作方式，如果您想先了解更多信息，请阅读Tera 模板文档。

所有模板都在templates目录中。如果您不确定模板中有哪些变量可用，您可以{{ __tera_context }}在模板中放置以打印整个上下文。

除提要和站点地图外，所有模板均提供一些变量：

config：语言感知配置
current_pathbase_url:当前页面的路径（不带的完整 URL ），始终以 a 开头/
current_url: 当前页面的完整 URL
lang: 当前页面的语言

配置变量可以像在 HTML 中一样访问config.variable，例如使用{{ config.base_url }}. 404模板没有get current_pathand current_url（这个信息无法确定）。

除了config上面提到的属性之外，它还获取config.mode它是在build,serve还是中运行check。

🔗标准模板

默认情况下，Zola 会寻找三个模板：index.html，应用于网站主页；section.html, 它适用于所有部分（通过在您的content目录中创建目录生成的任何 HTML 页面）；和 page.html，它适用于所有页面（通过 .md在您的content目录中创建文件生成的任何 HTML 页面）。

主页始终是一个部分（无论它是否包含其他页面）。因此，index.html和section.html模板都可以访问节变量。该page.html模板可以访问页面变量。下一节将更详细地描述页面和部分变量。

🔗内置模板

Zola 带有四个内置模板：atom.xml和rss.xml（在 Feeds中描述）、（在Sitemapsitemap.xml中描述）和（在Robots.txt中描述）。此外，主题可以添加自己的模板，如果没有被覆盖，这些模板将被应用。您可以通过在正确路径中创建具有相同名称的模板来覆盖内置或主题模板。例如，您可以通过创建文件来覆盖 Atom 模板。robots.txttemplates/atom.xml

🔗自定义模板

除了标准的index.html和模板之外，您还可以通过在目录中创建文件来创建自定义section.html模板。默认情况下不会使用这些自定义模板。相反，只有当您通过将front-matter 变量设置为该模板的路径（或者如果您在另一个应用的模板中）来应用它时，才会使用自定义模板。例如，如果您为站点的“关于”页面创建了一个名为的自定义模板，您可以通过在页面中包含以下前端内容来将其应用于您的页面：page.html.htmltemplatestemplateincludeabout.htmlabout.mdabout.md

+++
title = "About Us"
template = "about.html"
+++

自定义模板不需要位于templates目录的根目录中。例如，product_pages/with_pictures.html是一个有效的模板。

🔗内置过滤器

除了Tera 中已有的过滤器之外，Zola 添加了一些过滤器。

🔗降价

使用 Markdown 将给定变量转换为 HTML。与页面/部分 Markdown 呈现相比有一些差异：

此过滤器评估的短代码无法访问当前呈现上下文：config将可用，但访问section或page（除其他外）来自过滤器内调用的短代码markdown将阻止您的站点构建（请参阅此讨论）
lang在短代码中将始终等于网站的config.default_language（或en其他）；这应该不是问题，但如果在大多数情况下是这样，但是如果您需要在此过滤器中使用语言感知的简码，请参阅文档的简码上下文部分。

默认情况下，过滤器会将所有文本包装在一个段落中。要禁用此行为，您可以传递true给内联参数：

{{ some_text | markdown(inline=true) }}

您不需要将此过滤器与page.contentor 一起使用section.content，内容已经呈现。

🔗 base64_encode

将变量编码为 base64。

🔗 base64_decode

从 base64 解码变量。

🔗数字格式

将数字格式化为其字符串表示形式。

{{ 1000000 | num_format }}
<!-- 1,000,000 -->

默认情况下，这将使用 config.toml 中设置的语言环境来格式化数字config.default_language。

要为特定区域设置格式化数字，您可以使用参数locale并传递所需区域设置的名称：

{{ 1000000 | num_format(locale="en-IN") }}
<!-- 10,00,000 -->

🔗内置函数

Zola在 Tera 的内置功能中添加了一些 Tera 功能，以便更轻松地开发复杂的网站。

🔗文件搜索逻辑

get_page对于通过和以外的方式在磁盘上搜索文件的函数get_section，适用以下逻辑。

基本目录是 Zola 根目录，config.toml其中
对于给定的路径：如果它以开头@/，则将其替换为content/instead 并修剪任何前导/
按此顺序搜索以下位置，返回文件存在的第一个位置：
1. $base_directory + $路径
2. $base_directory + "静态/" + $路径
3. $base_directory + "内容/" + $路径
4. $base_directory + $output_path + $path
5. $base_directory + "themes" + $theme + "static/" + $path （仅当使用主题时）

实际上，这意味着@/some/image.jpg,/content/some/image.jpg和content/some/image.jpg将指向同一事物。

如果路径在 Zola 目录之外，则会出错。

🔗`get_page`

获取文件的路径.md并返回关联的页面。基本路径是content目录。

{% set page = get_page(path="blog/page2.md") %}

🔗`get_section`

获取文件的路径_index.md并返回关联的部分。基本路径是content目录。

{% set section = get_section(path="blog/_index.md") %}

如果只需要该部分的元数据，则可以传递metadata_only=true给该函数：

{% set section = get_section(path="blog/_index.md", metadata_only=true) %}

🔗`get_taxonomy_url`

获取找到的分类项的永久链接。

{% set url = get_taxonomy_url(kind="categories", name=page.taxonomies.category, lang=page.lang) %}

name几乎总是来自变量，但如果您想手动执行此操作，该值应与前面的值相同，而不是 slugified 版本。

lang（可选）默认为config.default_languageconfig.toml

required（可选）如果定义了分类法但没有任何内容使用它则抛出错误。默认为真。

🔗`get_taxonomy`

获取特定种类的整个分类法。

{% set categories = get_taxonomy(kind="categories") %}

输出的类型是：

kind: TaxonomyConfig;
items: Array<TaxonomyTerm>;

lang（可选）默认为config.default_languageconfig.toml

required（可选）如果定义了分类法但没有任何内容使用它则抛出错误。默认为真。

有关这些类型的完整文档，请参阅分类法文档。

🔗`get_taxonomy_term`

从特定种类的分类法中获取单个术语。

{% set categories = get_taxonomy_term(kind="categories", term="term_name") %}

输出的类型是单个TaxonomyTerm项目。

lang（可选）默认为config.default_languageconfig.toml

include_pages（可选）默认为真。如果为 false，pages则TaxonomyTerm无论该术语实际存在哪些页面，该项目都将为空。page_count在这两种情况下都将正确反映该术语的页数。

required（可选）如果未找到分类法或术语。

有关这些类型的完整文档，请参阅分类法文档。

🔗`get_url`

获取给定路径的永久链接。如果路径以开头@/，它将像 Markdown 中使用的那样被视为内部链接，从根content目录开始并经过验证。

{% set url = get_url(path="@/blog/_index.md") %}

它接受一个可选参数，lang以便计算多语言网站中的语言感知 URL。假设config.base_urlis "http://example.com"，以下代码段将：

返回"http://example.com/blog/"如果config.default_language是"en"
"http://example.com/en/blog/"如果config.default_language不是则返回并"en"出现"en"在config.languages
否则失败，并显示错误消息"'en' is not an authorized language (check config.languages)."

{% set url = get_url(path="@/blog/_index.md", lang="en") %}

这也可用于获取静态文件的永久链接，例如，如果您想链接到位于以下位置的文件static/css/app.css：

{{ get_url(path="css/app.css") }}

默认情况下，链接不会有尾部斜线。trailing_slash=true您可以通过传递给函数来强制执行一个get_url。一个例子是：

{{ get_url(path="css/app.css", trailing_slash=true) }}

在非内部链接的情况下，您还可以通过传递给?h=<sha256>函数在 URL 的末尾添加格式的缓存块。在这种情况下，路径将需要解析为实际文件。有关详细信息，请参见文件搜索逻辑。cachebust=trueget_url

🔗`get_hash`

返回文件或字符串文字的哈希摘要（SHA-256、SHA-384 或 SHA-512）。

它可以采用以下参数：

path: 必填，详见文件查找逻辑
or literal : 强制，要散列的字符串值
sha_type: 可选，256,384或之一512，默认为384
base64: 可选，true或者false, 默认为true. 是否将哈希编码为base64

要么path要么literal必须给。

{{ get_hash(literal="Hello World", sha_type=256) }}
{{ get_hash(path="static/js/app.js", sha_type=256) }}

base64 当其参数设置为时，该函数还可以输出 base64 编码的哈希值true。这可用于实现子资源完整性。

<script src="{{ get_url(path="static/js/app.js") }}"
  integrity="sha384-{{ get_hash(path="static/js/app.js", sha_type=384, base64=true) | safe }}"></script>

请注意，子资源完整性通常在使用get_hash不支持的外部脚本时使用。

🔗`get_image_metadata`

获取图像的元数据。这支持 JPEG、PNG、WebP、BMP、GIF 和 SVG 等常见格式。

它可以采用以下参数：

path: 必填，详见文件查找逻辑
allow_missing: 可选，true或者false, 默认为false. 丢失的文件是否应该引发错误。

该方法返回一个包含width,height和format（小写值作为字符串）的映射。

  {% set meta = get_image_metadata(path="...") %}
  Our image (.{{meta.format}}) has format is {{ meta.width }}x{{ meta.height }}

🔗`load_data`

从文件、URL 或字符串文字加载数据。支持的文件类型包括toml、json、csv、bibtex、yaml / yml和xml并且仅支持 UTF-8 编码。

任何其他文件类型都将作为纯文本加载。

根据文件搜索逻辑，参数path指定本地数据文件的路径。

{% set data = load_data(path="content/blog/story/data.toml") %}

或者，url参数指定要加载的远程 URL 的位置。

{% set data = load_data(url="https://en.wikipedia.org/wiki/Commune_of_Paris") %}

或者，literal参数指定对象文字。注意：如果format未指定参数，则假定为纯文本。

{% set data = load_data(literal='{"name": "bob"}', format="json") %}
{{ data["name"] }}

注意：required参数与参数结合使用时无效literal。

可选的required布尔参数可以设置为 false，这样丢失的数据（HTTP 错误或未找到本地文件）不会产生错误，而是返回空值。但是，本地文件的权限问题和无法解析为请求的数据格式的无效数据仍然会产生错误，即使使用required=false.

下面的代码片段从维基百科页面输出 HTML，如果页面无法访问或未返回成功的 HTTP 代码，则输出“未找到数据”：

{% set data = load_data(url="https://en.wikipedia.org/wiki/Commune_of_Paris", required=false) %}
{% if data %}{{ data | safe }}{% else %}No data found{% endif %}

可选format参数允许您指定和覆盖指定文件或 URL 中包含的数据类型。有效条目为toml、json、csv、bibtex、yaml或xml。plain如果format未指定参数，则使用路径扩展。如果是文字，plain则假定为format未指定。

{% set data = load_data(path="content/blog/story/data.txt", format="json") %}

plain当您的文件具有受支持的扩展名但您想将其作为纯文本加载时，请使用该格式。

对于toml、json、yaml和xml，数据被加载到与原始数据文件匹配的结构中；然而，对于csv来说，没有这种结构的原生概念。相反，数据被分成包含标题和记录的数据结构。请参阅下面的示例以了解其工作原理。

在模板中：

{% set data = load_data(path="content/blog/story/data.csv") %}

在content/blog/story/data.csv文件中：

Number, Title
1,Gutenberg
2,Printing

解析数据的等效 json 值将存储在data模板的变量中：

{
    "headers": ["Number", "Title"],
    "records": [
        ["1", "Gutenberg"],
        ["2", "Printing"]
    ],
}

该格式将数据加载到与nom-bibtex cratebibtex使用的格式相匹配的结构中。以下是 bibtex 格式的数据示例：

@preamble{"A bibtex preamble" # " this is."}

@Comment{
    Here is a comment.
}

Another comment!

@string(name = "Vincent Prouillet")
@string(github = "https://github.com/getzola/zola")

@misc {my_citation_key,
    author= name,
    title = "Zola",
    note = "github: " # github
}                                                    }

以下是生成的 bibtex 数据结构的 json 等效格式：

{
    "preambles": ["A bibtex preamble this is."],
    "comments": ["Here is a comment.", "Another comment!"],
    "variables": {
        "name": "Vincent Prouillet",
        "github": "https://github.com/getzola/zola"
    },
    "bibliographies": [
        {
            "entry_type": "misc",
            "citation_key": "my_citation_key",
            "tags": {
                "author": "Vincent Prouillet",
                "title": "Zola",
                "note": "github: https://github.com/getzola/zola"
            }
        }
    ]
}

最后，可以从模板访问 bibtex 数据，如下所示：

{% set tags = data.bibliographies[0].tags %}
This was generated using {{ tags.title }}, authored by {{ tags.author }}.

🔗远程内容

您可以从远程 URL 加载数据，而不是使用文件。url这可以通过指定参数而load_data不是来完成path。

{% set response = load_data(url="https://api.github.com/repos/getzola/zola") %}
{{ response }}

默认情况下，响应主体将不经解析返回。这可以通过使用format如下参数进行更改。

{% set response = load_data(url="https://api.github.com/repos/getzola/zola", format="json") %}
{{ response }}

当没有指定其他参数时，将始终使用 HTTP GET 请求检索 URL。使用参数method，从 0.14.0 版本开始，您还可以选择使用 POST 请求检索 URL。

使用时，method="POST"您还可以使用参数body和content_type。参数体是POST请求中发送的实际内容。该参数content_type应该是正文的 mimetype。

此示例将向 kroki 服务发出 POST 请求以生成 SVG。

{% set postdata = load_data(url="https://kroki.io/blockdiag/svg", format="plain", method="POST" ,content_type="text/plain", body="blockdiag {
  'Doing POST' -> 'using load_data'
  'using load_data' -> 'can generate' -> 'block diagrams';
  'using load_data' -> is -> 'very easy!';

  'Doing POST' [color = 'greenyellow'];
  'block diagrams' [color = 'pink'];
  'very easy!' [color = 'orange'];
}")%}
{{postdata|safe}}

如果您需要对 HTTP 标头进行额外处理，则可以使用该headers参数。当资源需要身份验证或需要通过特殊标头传递其他参数时，您可能需要此参数。请注意，标头将附加到 Zola 本身设置的默认标头，而不是替换它们。

此示例将向 GitHub markdown 呈现服务发出 POST 请求。

{% set postdata = load_data(url="https://api.github.com/markdown", format="plain", method="POST", content_type="application/json", headers=["accept=application/vnd.github.v3+json"], body='{"text":"headers support added in #1710, commit before it: b3918f124d13ec1bedad4860c15a060dd3751368","context":"getzola/zola","mode":"gfm"}')%}
{{postdata|safe}}

以下示例显示如何将 GraphQL 查询发送到 GitHub（需要身份验证）。如果你想在自己的机器上尝试这个例子，你需要提供一个GitHub PAT（Personal Access Token），你可以通过这个链接获取access token：https://github.com/settings/tokens 然后设置GITHUB_TOKEN 环境变量到您获得的访问令牌。

{% set token = get_env(name="GITHUB_TOKEN") %}
{% set postdata = load_data(url="https://api.github.com/graphql", format="json", method="POST" ,content_type="application/json", headers=["accept=application/vnd.github.v4.idl", "authentication=Bearer " ~ token], body='{"query":"query { viewer { login }}"}')%}
{{postdata|safe}}

如果您需要指定多个具有相同名称的标头，您可以这样指定它们：

headers=["accept=application/json,text/html"]

这相当于Accept带有application/json和的两个标头text/html。

如果它不起作用，您可以多次指定标头以达到类似的效果：

headers=["accept=application/json", "accept=text/html"]

🔗数据缓存

数据文件加载和远程请求在构建期间缓存在内存中，因此不会向同一端点发出多个请求。URL根据URL进行缓存，数据文件根据文件修改时间进行缓存。缓存时也会考虑格式，因此如果加载了两种不同的格式，请求将被发送两次。

🔗`trans`

获取给定的翻译key，对于default_language，lang给定的用法或活动语言：

{{ trans(key="title") }}
{{ trans(key="title", lang="fr") }}
{{/* trans(key="title", lang=lang) */}}

🔗`resize_image`

调整图像文件的大小。请参阅内容/图像处理以获取完整文档。

概述

🔗标准模板

🔗内置模板

🔗自定义模板

🔗内置过滤器

🔗降价

🔗 base64_encode

🔗 base64_decode

🔗数字格式

🔗内置函数

🔗文件搜索逻辑

🔗get_page

🔗get_section

🔗get_taxonomy_url

🔗get_taxonomy

🔗get_taxonomy_term

🔗get_url

🔗get_hash

🔗get_image_metadata

🔗load_data

🔗远程内容

🔗数据缓存

🔗trans

🔗resize_image

🔗`get_page`

🔗`get_section`

🔗`get_taxonomy_url`

🔗`get_taxonomy`

🔗`get_taxonomy_term`

🔗`get_url`

🔗`get_hash`

🔗`get_image_metadata`

🔗`load_data`

🔗`trans`

🔗`resize_image`