* Update installation.md * Update cli-usage.md * Update installation.md * Update directory-structure.md * Update configuration.md * Update overview.md * Update section.md * Update page.md * Update section.md * Update configuration.md * Update page.md * Update section.md * Update page.md * Update shortcodes.md * Update linking.md * Update table-of-contents.md * Update syntax-highlighting.md * Update taxonomies.md * Update search.md * Update sass.md * Update index.md * Update multilingual.md * Update overview.md * Update pages-sections.md * Update pagination.md * Update taxonomies.md * Update rss.md * Update sitemap.md * Update robots.md * Update 404.md * Update archive.md * Update overview.md * Update installing-and-using-themes.md * Update creating-a-theme.md * Update netlify.md * Update github-pages.md * Update gitlab-pages.md * Update index.md * Update page.md * Update section.md * Updates.
252 lines
8.9 KiB
Markdown
252 lines
8.9 KiB
Markdown
+++
|
|
title = "Overview"
|
|
weight = 10
|
|
+++
|
|
|
|
Zola uses the [Tera](https://tera.netlify.com) template engine, which is very similar
|
|
to Jinja2, Liquid and Twig.
|
|
|
|
As this documentation will only talk about how templates work in Zola, please read
|
|
the [Tera template documentation](https://tera.netlify.com/docs#templates) if you want
|
|
to learn more about it first.
|
|
|
|
All templates live in the `templates` directory. If you are not sure what variables are available in a template,
|
|
you can place `{{ __tera_context }}` in the template to print the whole context.
|
|
|
|
A few variables are available on all templates except RSS and the sitemap:
|
|
|
|
- `config`: the [configuration](@/documentation/getting-started/configuration.md) without any modifications
|
|
- `current_path`: the path (full URL without `base_url`) of the current page, never starting with a `/`
|
|
- `current_url`: the full URL for the current page
|
|
- `lang`: the language for the current page; `null` if the page/section doesn't have a language set
|
|
|
|
The 404 template does not get `current_path` and `current_url` (this information cannot be determined).
|
|
|
|
## Standard templates
|
|
By default, Zola will look for three templates: `index.html`, which is applied
|
|
to the site homepage; `section.html`, which is applied to all sections (any HTML
|
|
page generated by creating a directory within your `content` directory); and
|
|
`page.html`, which is applied to all pages (any HTML page generated by creating an
|
|
`.md` file within your `content` directory).
|
|
|
|
The homepage is always a section (regardless of whether it contains other pages).
|
|
Thus, the `index.html` and `section.html` templates both have access to the
|
|
section variables. The `page.html` template has access to the page variables.
|
|
The page and section variables are described in more detail in the next section.
|
|
|
|
## Built-in templates
|
|
Zola comes with three built-in templates: `rss.xml`, `sitemap.xml` and
|
|
`robots.txt` (each is described in its own section of this documentation).
|
|
Additionally, themes can add their own templates, which will be applied if not
|
|
overridden. You can override built-in or theme templates by creating a template with
|
|
the same name in the correct path. For example, you can override the RSS template by
|
|
creating a `templates/rss.xml` file.
|
|
|
|
## Custom templates
|
|
In addition to the standard `index.html`, `section.html` and `page.html` templates,
|
|
you may also create custom templates by creating an `.html` file in the `templates`
|
|
directory. These custom templates will not be used by default. Instead, a custom template will _only_ be used if you apply it by setting the `template` front-matter variable to the path for that template (or if you `include` it in another template that is applied). For example, if you created a custom template for your site's About page called `about.html`, you could apply it to your `about.md` page by including the following front matter in your `about.md` page:
|
|
|
|
```md
|
|
+++
|
|
title = "About Us"
|
|
template = "about.html"
|
|
+++
|
|
```
|
|
|
|
Custom templates are not required to live at the root of your `templates` directory.
|
|
For example, `product_pages/with_pictures.html` is a valid template.
|
|
|
|
## Built-in filters
|
|
Zola adds a few filters in addition to [those](https://tera.netlify.com/docs/templates/#built-in-filters) already present
|
|
in Tera.
|
|
|
|
### markdown
|
|
Converts the given variable to HTML using Markdown. This doesn't apply any of the
|
|
features that Zola adds to Markdown; for example, internal links and shortcodes won't work.
|
|
|
|
By default, the filter will wrap all text in a paragraph. To disable this behaviour, you can
|
|
pass `true` to the inline argument:
|
|
|
|
```jinja2
|
|
{{ some_text | markdown(inline=true) }}
|
|
```
|
|
|
|
### base64_encode
|
|
Encode the variable to base64.
|
|
|
|
### base64_decode
|
|
Decode the variable from base64.
|
|
|
|
|
|
## Built-in global functions
|
|
|
|
<<<<<<< HEAD
|
|
Zola adds a few global functions to [those in Tera](https://tera.netlify.com/docs#built-in-functions) in order to make it easier to develop complex sites.
|
|
=======
|
|
Zola adds a few global functions to [those in Tera](https://tera.netlify.com/docs/templates/#built-in-functions)
|
|
to make it easier to develop complex sites.
|
|
>>>>>>> Simple clean up of documentation. (#849)
|
|
|
|
|
|
### `get_page`
|
|
Takes a path to an `.md` file and returns the associated page.
|
|
|
|
```jinja2
|
|
{% set page = get_page(path="blog/page2.md") %}
|
|
```
|
|
|
|
### `get_section`
|
|
Takes a path to an `_index.md` file and returns the associated section.
|
|
|
|
```jinja2
|
|
{% set section = get_section(path="blog/_index.md") %}
|
|
```
|
|
|
|
If you only need the metadata of the section, you can pass `metadata_only=true` to the function:
|
|
|
|
```jinja2
|
|
{% set section = get_section(path="blog/_index.md", metadata_only=true) %}
|
|
```
|
|
|
|
### ` get_url`
|
|
Gets the permalink for the given path.
|
|
If the path starts with `@/`, it will be treated as an internal
|
|
link like the ones used in Markdown, starting from the root `content` directory.
|
|
|
|
```jinja2
|
|
{% set url = get_url(path="@/blog/_index.md") %}
|
|
```
|
|
|
|
This can also be used to get the permalinks for static assets, for example if
|
|
we want to link to the file that is located at `static/css/app.css`:
|
|
|
|
```jinja2
|
|
{{/* get_url(path="css/app.css") */}}
|
|
```
|
|
|
|
By default, assets will not have a trailing slash. You can force one by passing `trailing_slash=true` to the `get_url` function.
|
|
An example is:
|
|
|
|
```jinja2
|
|
{{/* get_url(path="css/app.css", trailing_slash=true) */}}
|
|
```
|
|
|
|
In the case of non-internal links, you can also add a cachebust of the format `?t=1290192` at the end of a URL
|
|
by passing `cachebust=true` to the `get_url` function.
|
|
|
|
|
|
### `get_image_metadata`
|
|
Gets metadata for an image. Currently, the only supported keys are `width` and `height`.
|
|
|
|
```jinja2
|
|
{% set meta = get_image_metadata(path="...") %}
|
|
Our image is {{ meta.width }}x{{ meta.height }}
|
|
```
|
|
|
|
### `get_taxonomy_url`
|
|
Gets the permalink for the taxonomy item found.
|
|
|
|
```jinja2
|
|
{% set url = get_taxonomy_url(kind="categories", name=page.taxonomies.category) %}
|
|
```
|
|
|
|
`name` will almost always come from a variable but in case you want to do it manually,
|
|
the value should be the same as the one in the front matter, not the slugified version.
|
|
|
|
### `get_taxonomy`
|
|
Gets the whole taxonomy of a specific kind.
|
|
|
|
```jinja2
|
|
{% set categories = get_taxonomy(kind="categories") %}
|
|
```
|
|
|
|
### `load_data`
|
|
Loads data from a file or URL. Supported file types include *toml*, *json* and *csv*.
|
|
Any other file type will be loaded as plain text.
|
|
|
|
The `path` argument specifies the path to the data file relative to your base directory, where your `config.toml` is.
|
|
As a security precaution, if this file is outside the main site directory, your site will fail to build.
|
|
|
|
```jinja2
|
|
{% set data = load_data(path="content/blog/story/data.toml") %}
|
|
```
|
|
|
|
The optional `format` argument allows you to specify and override which data type is contained
|
|
within the file specified in the `path` argument. Valid entries are `toml`, `json`, `csv`
|
|
or `plain`. If the `format` argument isn't specified, then the path extension is used.
|
|
|
|
```jinja2
|
|
{% set data = load_data(path="content/blog/story/data.txt", format="json") %}
|
|
```
|
|
|
|
Use the `plain` format for when your file has a toml/json/csv extension but you want to load it as plain text.
|
|
|
|
For *toml* and *json*, the data is loaded into a structure matching the original data file;
|
|
however, for *csv* there is no native notion of such a structure. Instead, the data is separated
|
|
into a data structure containing *headers* and *records*. See the example below to see
|
|
how this works.
|
|
|
|
In the template:
|
|
```jinja2
|
|
{% set data = load_data(path="content/blog/story/data.csv") %}
|
|
```
|
|
|
|
In the *content/blog/story/data.csv* file:
|
|
```csv
|
|
Number, Title
|
|
1,Gutenberg
|
|
2,Printing
|
|
```
|
|
|
|
The equivalent json value of the parsed data would be stored in the `data` variable in the
|
|
template:
|
|
```json
|
|
{
|
|
"headers": ["Number", "Title"],
|
|
"records": [
|
|
["1", "Gutenberg"],
|
|
["2", "Printing"]
|
|
],
|
|
}
|
|
```
|
|
|
|
#### Remote content
|
|
|
|
Instead of using a file, you can load data from a remote URL. This can be done by specifying a `url` parameter
|
|
to `load_data` rather than `path`.
|
|
|
|
```jinja2
|
|
{% set response = load_data(url="https://api.github.com/repos/getzola/zola") %}
|
|
{{ response }}
|
|
```
|
|
|
|
By default, the response body will be returned with no parsing. This can be changed by using the `format` argument
|
|
as below.
|
|
|
|
|
|
```jinja2
|
|
{% set response = load_data(url="https://api.github.com/repos/getzola/zola", format="json") %}
|
|
{{ response }}
|
|
```
|
|
|
|
#### Data caching
|
|
|
|
Data file loading and remote requests are cached in memory during the build, so multiple requests aren't made
|
|
to the same endpoint.
|
|
URLs are cached based on the URL, and data files are cached based on the file modified time.
|
|
The format is also taken into account when caching, so a request will be sent twice if it's loaded with two
|
|
different formats.
|
|
|
|
### `trans`
|
|
Gets the translation of the given `key`, for the `default_language` or the `lang`uage given
|
|
|
|
```jinja2
|
|
{{/* trans(key="title") */}}
|
|
{{/* trans(key="title", lang="fr") */}}
|
|
```
|
|
|
|
### `resize_image`
|
|
Resizes an image file.
|
|
Pease refer to [_Content / Image Processing_](@/documentation/content/image-processing/index.md) for complete documentation.
|