zola/docs/content/documentation/templates/overview.md

+++
title = "Overview"
weight = 10
+++

Gutenberg uses the [Tera](https://tera.netlify.com) template engine and is very similar
to Jinja2, Liquid or Twig.

As this documentation will only talk about how templates work in Gutenberg, 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 just stick `{{ __tera_context }}` in it
to print the whole context.

A few variables are available on all templates minus RSS and sitemap:

- `config`: the [configuration](./documentation/getting-started/configuration.md) without any modifications
- `current_path`: the path (full URL without the `base_url`) of the current page, never starting with a `/`
- `current_url`: the full URL for that page

## Standard Templates
By default, Gutenberg 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 a
`.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 of this documentation.

## Built-in Templates
Gutenberg comes with three built-in templates: `rss.xml`, `sitemap.xml`, and
`robots.txt` (each described in their 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
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 a `.html` file in the `templates`
directory.  These custom templates will not be used by default.  Instead, the 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
Gutenberg adds a few filters, in addition of the ones already present in Tera.

### markdown
Converts the given variable to HTML using Markdown. This doesn't apply any of the
features that Gutenberg adds to Markdown: internal links, shortcodes etc won't work.

By default, the filter will wrap all text into a paragraph. To disable that, 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
Gutenberg adds a few global functions to Tera in order to make it easier to develop complex sites.

### `get_page`
Takes a path to a `.md` file and returns the associated page

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

### `get_section`
Takes a path to a `_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 understood as an internal
link like the ones used in markdown.

```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_taxonomy_url`
Gets the permalink for the taxonomy item found.

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

The `name` will almost 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_url(kind="categories") %}
```

### `load_data`
Loads data from a file. Supported file types include *toml*, *json* and *csv*.

The `path` argument specifies the path to the data file relative to your content directory.

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

The optional `kind` 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"*
or *"csv"*. 

```jinja2
{% set data = load_data(path="blog/story/data.txt", kind="json") %}
```

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 seperated
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="blog/story/data.csv") %}
```

In the *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"]
    ],
}
 ```

### `trans`
Gets the translation of the given `key`, for the `default_language` or the `language 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.