github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-07 20:30:36 -05:00
Code Issues Projects Releases Packages Wiki Activity

docs: Improve documentation for block templates

Browse source 
Hopefully.

Fixes #2363
This commit is contained in:
Bjørn Erik Pedersen 2016-12-15 22:02:21 +01:00
parent a3a67163f9
commit 79b2725ac4
2 changed files with 26 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
docs/content/templates/ace.md
View file

@ -29,20 +29,9 @@ For template documentation, follow the links from the [Ace project](https://gith
One noticeable difference between Ace and the others is the inheritance support through [base and inner templates](https://github.com/yosssi/ace/tree/master/examples/base_inner_template).
In Hugo the base template will be chosen in the following order:
In Hugo the base template will be chosen with the same ruleset as for [Go templates](/templates/blocks/).
```
1. <current-path>/<template-name>-baseof.ace, e.g. list-baseof.ace
2. <current-path>/baseof.ace
3. _default/<template-name>-baseof.ace, e.g. list-baseof.ace.
4. _default/baseof.ace
5. <themedir>/layouts/_default/<template-name>-baseof.ace
6. <themedir>/layouts/_default/baseof.ace
```
In the above, `current-path` is where the corresponding inner template lives, `list.ace`, `single.ace`, `index.ace` ...
```
.:
index.ace

27
docs/content/templates/blocks.md
View file

@ -9,11 +9,34 @@ title: Block Templates
weight: 80
---
Go 1.6 includes a powerful new keyword, `block`. This construct allows you to define the outer shell of your pages in a single "base" template, filling in or overriding portions as necessary.
Go 1.6 includes a powerful new keyword, `block`. This construct allows you to define the outer shell of your pages one ore more master template(s), filling in or overriding portions as necessary.
## Base template lookup
This is the order Hugo searches for a base template:
1. /layouts/_current-path_/_template-name_-baseof.html, e.g. list-baseof.html.
2. /layouts/_current-path_/baseof.html
3. /layouts/_default/_template-name_-baseof.html e.g. list-baseof.html.
4. /layouts/_default/baseof.html
For each of the steps above, it will first look in the project, then, if theme is set, in the theme's layouts folder. Hugo picks the first base template found.
As an example, with a site using the theme `exampletheme`, when rendering the section list for the section `post`. Hugo picks the `section/post.html` as the template and this template has a `define` section that indicates it needs a base template. This is then the lookup order:
1. `/layouts/section/post-baseof.html`
2. `/themes/exampletheme/layouts/section/post-baseof.html`
3. `/layouts/section/baseof.html`
4. `/themes/exampletheme/layouts/section/baseof.html`
5. `/layouts/_default/post-baseof.html`
6. `/themes/exampletheme/layouts/_default/post-baseof.html`
7. `/layouts/_default/baseof.html`
8. `/themes/exampletheme/layouts/_default/baseof.html`
## Define the base template
Let's define a simple base template (`_default/baseof.html`), a shell from which all our pages will start. To find a base template, Hugo searches the same paths and file names as it does for [Ace templates]({{< relref "templates/ace.md" >}}), just with files suffixed `.html` rather than `.ace`.
Let's define a simple base template (`_default/baseof.html`), a shell from which all our pages will start.
```html
<!DOCTYPE html>