diff --git a/docs/kiln.1.scd b/docs/kiln.1.scd index 4069d89..494db9b 100644 --- a/docs/kiln.1.scd +++ b/docs/kiln.1.scd @@ -169,17 +169,102 @@ 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*. -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. - -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 more information on the Go templating language, see https://golang.org/pkg/text/template/. +## PAGE AND INDEX TEMPLATES + +The content for page and index templates can be accessed using the *.Content* +page variable. For example: + +``` +page header +{{ .Content }} +page footer +``` + +Other page variables are documented in *PAGE VARIABLES*. + +In HTML templates, page content is escaped by default. If the content is known +to be safe, it must be marked as safe to avoid escaping. For example: + +``` + +{{ .Content | safeHTML }} + +``` + +See *TEMPLATE FUNCTIONS* for more information. + +## BASE TEMPLATES + +Base templates are inherited only by page and index templates. Base templates +generally define at least one block which can be customized by page and index +templates, according to the Go templating language. + +For example, the base template could contain: + +``` +{{ block "body" . }} + Blocks can have default content +{{ end }} +{{ block "extra_content" . }}{{ end }} +``` + +The page and index templates can then customize these blocks, for example: + +``` +{{ define "body" }} + Body goes here +{{ end }} +``` + +## TEMPLATE RESOLUTION + +The scope of a template is limited by the directory it is placed in. For +example, a page template in the templates/blog/ directory will only apply to +files in content/blog/. A page template placed in templates/ will only apply to +files in content/ and 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 found in the +template directory. + +For example, the page file content/blog/my_first_post.gmi will be rendered with +the template templates/blog/page.ext. If that template is not found, it falls +back to templates/\_default/page.ext. If that template is also not found, then +no template will be used. + +Base templates also follow the same rules. For example, the index template +templates/blog/index.ext inherits firstly from templates/blog/base.ext, and +then falls back to templates/\_default/base.ext if present. + +## 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. + +In HTML templates, the partial template content is escaped by default. If the +content is known to be safe, it must be marked as safe to avoid escaping. For +example: + +``` + +{{ partial "navbar.ext" . | safeHTML }} + +``` + +See *TEMPLATE FUNCTIONS* for more information. + # CONFIGURATION By default, kiln looks for a configuration file named "config.toml". An