aboutsummaryrefslogtreecommitdiffstats
path: root/man/ssg-templates.5
blob: 156eef9bb5c49b87472f4a946f7c5a25bbf85b3f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
.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}}
  <li><a href="{{.url}}">{{.name}}</a></li>
{{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 <array> <field> <value>
.Ed
.Pp
Returns items from an array where a field equals a value.
.Bd -literal -offset indent
{{range filter .projects "featured" true}}
  <li>{{.name}}</li>
{{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