docs/content/templates/_index.md (1438B)
1 +++
2 title = "Templates"
3 description = "Jinja2-compatible templates, a strict data model, and explicit selection"
4 weight = 30
5 sort_by = "weight"
6 +++
7
8 Templates live in `templates/` and are [minijinja] — Jinja2 syntax, so
9 `{% extends %}`, `{% block %}`, `{% include %}`, `{% macro %}` and filters all
10 work the way you expect.
11
12 ```
13 templates/
14 ├── base.html
15 ├── page.html
16 ├── section.html
17 └── partials/
18 ├── sidebar.html
19 └── toc.html
20 ```
21
22 ## Two things are stricter than you may be used to
23
24 **Undefined access is an error.** Rename a front matter key and the build stops
25 with the name of the template and the key, instead of rendering a page with a
26 hole in it. It is not the strictest setting available — `{% if optional %}` on
27 something that was never defined still works, because a template that cannot
28 ask "is this here?" is not usable for a site where pages differ.
29
30 **Everything is escaped by default.** `page.content` is already HTML, so it
31 needs `| safe`. That is one deliberate `| safe` in exchange for every other
32 value being safe without you thinking about it.
33
34 ## A snapshot per build
35
36 `templates/` is read once at the start of a build, and `include`/`extends`
37 resolve against that snapshot. Save a partial while the dev server is watching
38 and the rebuild it triggers sees one consistent set of files — never a
39 half-written one.
40
41 [minijinja]: https://github.com/mitsuhiko/minijinja