specter/kiln
1
0
Fork 0
mirror of https://git.sr.ht/~adnano/kiln synced 2024-12-27 22:29:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update template-related documentation

Browse source
This commit is contained in:
Edd Salkield 2022-09-25 18:03:39 +01:00 committed by adnano
parent 63b63a32e1
commit da0af1701c
1 changed files with 93 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

101
docs/kiln.1.scd
View file

@ -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:
```
<body>
{{ .Content | safeHTML }}
</body>
```
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:
```
<body>
{{ partial "navbar.ext" . | safeHTML }}
</body>
```
See *TEMPLATE FUNCTIONS* for more information.
# CONFIGURATION
By default, kiln looks for a configuration file named "config.toml". An