.Dd January 2, 2026
.Dt SSG-TEMPLATES 5
.Os
.Sh NAME
.Nm ssg-templates
.Nd ssg template format
.Sh DESCRIPTION
Templates use Go's
.Lk https://pkg.go.dev/html/template html/template
syntax. Each HTML file in the templates directory (default:
.Pa templates/ )
is processed and rendered to
the output directory with the same filename and directory structure.
.Sh DATA
Data from JSON files in the data directory (default:
.Pa data/ )
is made available to templates. Each file becomes a template variable named
after the file (without the
.Pa .json
extension).
.Pp
For example, if
.Pa data/projects.json
contains:
.Bd -literal -offset indent
[
{"name": "foo", "url": "https://example.com/foo", "featured": true},
{"name": "bar", "url": "https://example.com/bar", "featured": false}
]
.Ed
.Pp
It can be accessed in templates as
.Va .projects :
.Bd -literal -offset indent
{{range .projects}}
{{.name}}
{{end}}
.Ed
.Sh SYNTAX
Templates use Go's text/template syntax:
.Bl -tag -width Ds
.It Li {{.field}}
Output a field value.
.It Li {{range .items}}...{{end}}
Iterate over a list.
.It Li {{if .condition}}...{{end}}
Conditional rendering.
.It Li {{with .object}}...{{end}}
Set dot to the object for the block.
.El
.Pp
See the Go
.Lk https://pkg.go.dev/html/template html/template
documentation for full syntax details.
.Sh FUNCTIONS
In addition to Go's built-in template functions, the following
functions are available.
.Pp
All examples use data from
.Sx DATA .
.Ss filter
.Bd -literal
filter
.Ed
.Pp
Returns items from an array where a field equals a value.
.Bd -literal -offset indent
{{range filter .projects "featured" true}}
{{.name}}
{{end}}
.Ed
.Pp
This would output only "foo" since it has
.Va featured
set to
.Li true .
.Sh FILES
.Bl -tag -width Ds
.It Pa templates/*.html
HTML templates to render.
.It Pa data/*.json
JSON data files. Each becomes a template variable.
.El
.Sh SEE ALSO
.Xr ssg 1 ,
.Xr ssg-build 1