docs/content/templates/selection.md (1675B)
1 +++
2 title = "Choosing a template"
3 description = "Four steps, in order, and no cascade"
4 weight = 10
5 toc = true
6 +++
7
8 A page is rendered with the first of these that exists:
9
10 1. the `template` named in the page's front matter
11 2. `section.html`, if the page is a section index
12 3. the `page_template` set on the parent section's `_index.md`
13 4. `page.html`
14
15 That is the whole rule. Naming a `template` that does not exist is an error,
16 and the message lists the templates you do have.
17
18 ## Why it is four steps and not twenty
19
20 Hugo resolves templates through a lookup order built from kind × section × type
21 × layout × language × output format. It is more powerful, and it is the single
22 thing Hugo users get lost in most often — there is a decade-old request open
23 asking the tool to at least *print* which template it picked.
24
25 Four steps you can hold in your head need no such command. If you cannot tell
26 which template rendered a page, the rule is too complicated.
27
28 ## Setting a section's default
29
30 ```toml
31 # content/blog/_index.md
32 +++
33 title = "Blog"
34 page_template = "post.html"
35 +++
36 ```
37
38 Every page in `content/blog/` now renders with `post.html` unless it names its
39 own. Note that this reaches direct children only; a subsection sets its own.
40
41 ## Extending a base
42
43 The usual arrangement is one skeleton and thin templates on top:
44
45 ```html
46 {# templates/base.html #}
47 <!doctype html>
48 <html lang="{{ page.language }}">
49 <head><title>{{ page.title }}</title></head>
50 <body>{% block content %}{% endblock %}</body>
51 </html>
52 ```
53
54 ```html
55 {# templates/page.html #}
56 {% extends "base.html" %}
57 {% block content %}<article class="prose">{{ page.content | safe }}</article>{% endblock %}
58 ```