From 79b2725ac4242ee7bbc6f1f441352996679dcb1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Thu, 15 Dec 2016 22:02:21 +0100 Subject: [PATCH] docs: Improve documentation for block templates Hopefully. Fixes #2363 --- docs/content/templates/ace.md | 13 +------------ docs/content/templates/blocks.md | 27 +++++++++++++++++++++++++-- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/docs/content/templates/ace.md b/docs/content/templates/ace.md index d1f6ecc57..f0dbba694 100644 --- a/docs/content/templates/ace.md +++ b/docs/content/templates/ace.md @@ -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. /-baseof.ace, e.g. list-baseof.ace -2. /baseof.ace -3. _default/-baseof.ace, e.g. list-baseof.ace. -4. _default/baseof.ace -5. /layouts/_default/-baseof.ace -6. /layouts/_default/baseof.ace -``` -In the above, `current-path` is where the corresponding inner template lives, `list.ace`, `single.ace`, `index.ace` ... - -``` .: index.ace diff --git a/docs/content/templates/blocks.md b/docs/content/templates/blocks.md index 7073fa293..19a83fff3 100644 --- a/docs/content/templates/blocks.md +++ b/docs/content/templates/blocks.md @@ -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