Edd Salkield: 1 templates.go: Base template behaviour update 3 files changed, 109 insertions(+), 25 deletions(-)
Nice one, thanks! Just one question: why do we continue when `path == basePath` in templates.go?
To skip base templates (so that they don't inherit from themselves).
Copy & paste the following snippet into your terminal to import this patchset into git:
curl -s https://lists.sr.ht/~adnano/kiln-devel/patches/35576/mbox | git am -3Learn more about email & git
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
Thanks! To git@git.sr.ht:~adnano/kiln 299cb5e..84e9ee6 master -> master I've rebased this patch on top of my other recent changes. I've also split this patch into two and tweaked the documentation. If you have any feedback, let me know.