Base templates are inherited by index.ext and page.ext templates only.
Base template resolution falls back to _default.
Update template-related docs.
---
docs/kiln.1.scd | 112 ++++++++++++++++++++++++++++++++++++++++++------
page.go | 11 +----
templates.go | 11 ++++-
3 files changed, 109 insertions(+), 25 deletions(-)
diff --git a/docs/kiln.1.scd b/docs/kiln.1.scd
index 4069d89..6720b33 100644
--- a/docs/kiln.1.scd
+++ b/docs/kiln.1.scd
@@ -152,8 +152,14 @@ order.
# TEMPLATES DIRECTORY
-The templates directory contains templates for use when building the site.
-Templates use the Go templating language. The following templates are supported:
+The templates directory contains templates used when building the site.
+Templates use the Go templating language.
+Each page and index page defined in the content directory is optionally built
+using a template.
+
+Templates can optionally inherit from a base template.
+Atom feeds are also built using a template.
+The following templates are supported:
[[ *Template*
:[ *Description*
@@ -169,17 +175,101 @@ Templates use the Go templating language. The following templates are supported:
The extension of page and index templates is configurable and will replace
".ext" above. See *CONFIGURATION*.
+## PAGE AND INDEX TEMPLATES
+
+The content for page.ext and index.ext templates is inserted using the
+*.Content* page variable. For example:
+
+```
+page content
+{{ .Content }}
+more page content
+```
+
+Other page variables are documented in *PAGE VARIABLES*.
+
+The page content is escaped by default for safety. If the content is known safe,
+then an escaping template function needs to be invoked. For example:
+
+```
+page content
+{{ .Content | safeHTML }}
+more page content
+```
+
+See *TEMPLATE FUNCTIONS* for more information.
+
+## TEMPLATE RESOLUTION
+
The scope of a template is limited by the directory it is placed in. For
-example, a template in the templates/blog directory will only apply to files in
-content/blog.
+example, a template in the templates/blog/ directory will only apply to files in
+content/blog/. A template placed in templates/ will only apply to files in
+content/, but not its subdirectories.
+
+Fallback templates can be specified in the templates/\_default/ directory. These
+templates will apply only when the required kind of template is not defined
+in the template directory.
-Fallback templates can be specified in the templates/\_default directory. These
-templates will apply to any directory which does not have its own templates
-specified in the template directory.
+For example, content/blog/my_first_post.html inherits firstly from
+templates/blog/page.ext, and then falls back to templates/\_default/page.ext.
+
+templates/blog/index.ext inherits firstly from templates/blog/base.ext, and
+then falls back to templates/\_default/base.ext.
For more information on the Go templating language, see
https://golang.org/pkg/text/template/.
+## BASE TEMPLATES
+
+Base templates are inherited only by page.ext and index.ext templates. These
+generally define at least one block where the contents get inserted, according
+to the Go templating language.
+
+For example, the base template could contain:
+
+```
+{{ block "body" $ }}{{ end }}
+{{ block "extra_content" $ }}{{ end }}
+```
+
+Then the page.ext and index.ext templates must then define these blocks, for
+example:
+
+```
+{{ define "body" }}
+body goes here
+{{ end }}
+{{ define "extra_content" }}
+extra content goes here
+{{ end }}
+```
+
+## PARTIAL TEMPLATES
+
+Partial templates can be placed in the templates/\_partials directory.
+Partial templates can be executed from any other template using the *partial*
+function. For example, a template could contain:
+
+```
+{{ partial "navbar.ext" . }}
+```
+
+Then templates/\_partials/navbar.ext is executed. Since argument . is
+provided, all data from the current context is provided. See *TEMPLATE
+FUNCTIONS* for more information.
+
+The partial template content is escaped by default for safety. If the content
+is known safe, then an escaping template function needs to be invoked. For
+example:
+
+```
+page content
+{{ partial "navbar.ext" . | safeHTML }}
+more page content
+```
+
+See *TEMPLATE FUNCTIONS* for more information.
+
# CONFIGURATION
By default, kiln looks for a configuration file named "config.toml". An
@@ -471,7 +561,7 @@ The following page variables are available:
*.URL*
The URL of the page. If no base URL is configured, it is equivalent to
- *.Path*.
+ *.Path*
*.FilePath*
The path of the page file or directory relative to the content directory
@@ -553,12 +643,6 @@ Some of these variables are defined in feed configuration. See *FEEDS*.
Feed variables can be accessed from feed templates.
-## PARTIAL TEMPLATES
-
-Partial templates can be placed in the templates/\_partials directory.
-Partial templates can be executed from any other template with the *partial*
-function. See *TEMPLATE FUNCTIONS*.
-
## TEMPLATE FUNCTIONS
All templates have the following functions available to them:
diff --git a/page.go b/page.go
index d631b96..94f5405 100644
--- a/page.go
+++ b/page.go
@@ -194,10 +194,6 @@ func (p *Page) process(cfg *Site, task *Task) error {
// Create index
if p.index {
tmpl, ok := cfg.templates.FindTemplate(p.FilePath, "index"+task.TemplateExt)
- if !ok {
- // Try the base template
- tmpl, ok = cfg.templates.FindTemplate(p.FilePath, "base"+task.TemplateExt)
- }
if ok {
var b strings.Builder
if err := tmpl.Execute(&b, p); err != nil {
@@ -210,12 +206,7 @@ func (p *Page) process(cfg *Site, task *Task) error {
// Process pages
for i := range p.Pages {
var b strings.Builder
- tmpl, ok := cfg.templates.FindTemplate(p.FilePath, "page"+task.TemplateExt)
- if !ok {
- // Try the base template
- tmpl, ok = cfg.templates.FindTemplate(p.FilePath, "base"+task.TemplateExt)
- }
- if ok {
+ if tmpl, ok := cfg.templates.FindTemplate(p.FilePath, "page"+task.TemplateExt); ok {
if err := tmpl.Execute(&b, p.Pages[i]); err != nil {
return err
}
diff --git a/templates.go b/templates.go
index 6314c28..786c084 100644
--- a/templates.go
+++ b/templates.go
@@ -129,8 +129,17 @@ func (t *Templates) Load(dir string, exts []string) error {
if _, ok := extsMap[ext]; !ok {
continue
}
+ if strings.HasPrefix(path, "_partials/") {
+ continue
+ }
base := pathpkg.Join(pathpkg.Dir(path), "base"+ext)
- if tmpl, ok := t.tmpls[base]; ok {
+ tmpl, ok := t.tmpls[base]
+ if !ok {
+ base = pathpkg.Join("_default", "base"+ext)
+ tmpl, ok = t.tmpls[base]
+ }
+
+ if ok {
err := t.tmpls[path].AddParseTree(tmpl.Tree())
if err != nil {
return err
--
2.37.3