1kiln(1) General Commands Manual kiln(1)
2
3
4
6 kiln - a simple static site generator
7
9 kiln build [-c config]
10
11 kiln new path
12
13 kiln version
14
16 kiln build builds a kiln site.
17
18 kiln new creates a new kiln site at the given path.
19
20 kiln version prints version information for the kiln program.
21
23 kiln build
24 -c config
25 Specifies the configuration file to use. Defaults to "config.toml".
26
28 A kiln site is built in one or more steps called tasks. Tasks read con‐
29 tent from the content directory, process the content, and write the
30 content to the output directory. Tasks can also be configured to copy
31 static content to the output directory.
32
33 The following directories are common to all tasks:
34
35 ┌───────────┬─────────────────────┐
36 │Directory │ Description │
37 ├───────────┼─────────────────────┤
38 │content/ │ Content directory │
39 ├───────────┼─────────────────────┤
40 │templates/ │ Templates directory │
41 └───────────┴─────────────────────┘
42
44 The content directory contains site content files, called pages, op‐
45 tionally nested in subdirectories. Any file or directory in the content
46 directory whose name begins with "_" will be ignored, with the excep‐
47 tion of pages with the name "_index" (e.g. "_index.gmi").
48
49 Pages may be preprocessed, run through templates, and postprocessed (in
50 that order). Each operation takes the output of the last operation as
51 input.
52
53 Pages can specify dates in their filenames. For example, the page con‐
54 tent/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a
55 date of November 20, 2020.
56
57 Pages with the name "_index" are index pages and are treated specially.
58
59 FRONTMATTER
60 Pages can specify additional metadata in frontmatter. Frontmatter is
61 delimited by "---" and is specified in YAML. Newlines after the closing
62 delimiter are removed from the content.
63
64 Example:
65
66 ---
67 title: Page title
68 date: 2021-04-24
69 params:
70 custom: value
71 ---
72
73 Page content
74
75 The following keys are supported:
76
77 title
78 The title of the page.
79
80 Example:
81
82 ---
83 title: My first post
84 ---
85
86 date
87 The date of the page. Pages are sorted by date in reverse order, so
88 newer pages will be placed above older pages.
89
90 Example:
91
92 ---
93 date: 2021-05-21
94 ---
95
96 weight
97 The weight of the page. Pages are sorted by weight in increasing
98 order, so pages with a smaller weight will be placed above pages
99 with a larger weight.
100
101 Example:
102
103 ---
104 weight: 1
105 ---
106
107 params
108 Specifies extra parameters to be provided to templates.
109
110 Example:
111
112 ---
113 params:
114 key: value
115 ---
116
117 SORTING
118 Pages are sorted automatically. Pages are first ordered by weight in
119 increasing order, then by date from newest to oldest, and then by file‐
120 name in alphabetical order.
121
123 The templates directory contains templates for use when building the
124 site. Templates use the Go templating language. The following templates
125 are supported:
126
127 ┌──────────┬──────────────────────────┐
128 │Template │ Description │
129 ├──────────┼──────────────────────────┤
130 │page.ext │ Page template │
131 ├──────────┼──────────────────────────┤
132 │index.ext │ Directory index template │
133 ├──────────┼──────────────────────────┤
134 │base.ext │ Base template from which │
135 │ │ the page and index tem‐ │
136 │ │ plates inherit │
137 ├──────────┼──────────────────────────┤
138 │atom.xml │ Atom feed template │
139 └──────────┴──────────────────────────┘
140 The extension of page and index templates is configurable and will re‐
141 place ".ext" above. See CONFIGURATION.
142
143 The scope of a template is limited by the directory it is placed in.
144 For example, a template in the templates/blog directory will only apply
145 to files in content/blog.
146
147 Fallback templates can be specified in the templates/_default direc‐
148 tory. These templates will apply to any directory which does not have
149 its own templates specified in the template directory.
150
151 For more information on the Go templating language, see
152 https://golang.org/pkg/text/template/.
153
155 By default, kiln looks for a configuration file named "config.toml". An
156 alternative configuration file can be specified with the -c flag. See
157 OPTIONS.
158
159 The configuration file uses the TOML format.
160
161 The following keys are supported:
162
163 ┌──────┬─────────────────────┐
164 │Key │ Description │
165 ├──────┼─────────────────────┤
166 │title │ Site title │
167 ├──────┼─────────────────────┤
168 │urls │ A list of site URLs │
169 └──────┴─────────────────────┘
170 Site URLs may contain paths, but should not end with a trailing slash.
171 Multiple site URLs may be specified for sites that are available at
172 multiple locations.
173
174 FEEDS
175 Feeds can be specified in the [feeds] table of the configuration file.
176 Keys denote the path to the feed directory and values denote the title
177 of the feed.
178
179 Feeds are written to the output directory plus the feed directory plus
180 "atom.xml".
181
182 Example feed configuration:
183
184 # This will generate a feed which will be written to public/blog/atom.xml
185 [feeds]
186 "/blog/" = "My blog"
187
188 PERMALINKS
189 Permalinks can be used to rewrite page paths. Permalinks are specified
190 in the [permalinks] table of the configuration file. Keys denote a path
191 to a directory, and values use the Go templating language to rewrite
192 the final path of pages in that directory. The templates have the same
193 data that page templates have available to them (see PAGE TEMPLATES).
194
195 The following configuration will rewrite the paths of pages in the con‐
196 tent/blog directory to /YYYY/MM/DD/slug. For example, the file con‐
197 tent/blog/2021-05-12-hello-world.gmi will have a path of
198 /2021/05/12/hello-world/.
199
200 [permalinks]
201 "/blog/" = "/{{ .Date.Format `2006/01/02` }}/{{ path.Base .Permalink }}"
202
203 For more information on templates, see TEMPLATES.
204
205 TASKS
206 Tasks can be specified in the [[tasks]] array of tables.
207
208 The following configuration options are supported per task:
209
210 input
211 A list of input file extensions. Files in the content directory
212 with a matching extension will be processed.
213
214 Example:
215
216 [[tasks]]
217 input = [".gmi", ".md"]
218
219 output
220 The output file extension. Files written to the output directory
221 will use this extension.
222
223 Example:
224
225 [[tasks]]
226 output = ".html"
227
228 template
229 The template file extension. Templates with this file extension
230 will be used to format the content. If unset, no templates will be
231 used.
232
233 Example:
234
235 [[tasks]]
236 template = ".gmi"
237
238 preprocess
239 Maps file extensions to preprocess commands. Preprocess commands
240 will run before templating. The commands will be provided the con‐
241 tent of the page as standard input and should write the processed
242 content to standard output.
243
244 Example:
245
246 [[tasks]]
247 input = [".gmi", ".md"]
248 output = ".html"
249 preprocess.gmi = "gmnitohtml"
250 preprocess.md = "mdtohtml"
251
252 postprocess
253 Specifies a command which will run after templating and before con‐
254 tent is written to the output directory. It will be provided the
255 content of the page as standard input and should write the pro‐
256 cessed content to standard output.
257
258 Example:
259
260 [[tasks]]
261 input = [".gmi"]
262 output = ".html"
263 template = ".gmi"
264 postprocess = "gmnitohtml"
265
266 static_dir
267 Specifies a directory from which to read static content. All files
268 in this directory will be copied to the output directory without
269 modificiation. Static assets like images should be stored in this
270 directory. If unset, no static content directory will be used.
271
272 Example:
273
274 [[tasks]]
275 static_dir = "static"
276
277 output_dir
278 Specifies the directory to which output files will be written.
279
280 Example:
281
282 [[tasks]]
283 output_dir = "public"
284
285 ugly_urls
286 Specifies whether page permalinks will contain file extensions. By
287 default, clean URLs without any extension are used.
288
289 Example:
290
291 [[tasks]]
292 ugly_urls = true
293
294 The following configuration builds a simple Gemini site.
295
296 [[tasks]]
297 input = [".gmi"]
298 output = ".gmi"
299 template = ".gmi"
300 output_dir = "public"
301
302 The following configuration generates a Gemini text site and also ex‐
303 ports an HTML version of the site. This configuration makes use of the
304 gmnitohtml(1) command to convert Gemini text to HTML.
305
306 # Build the site
307 [[tasks]]
308 input = [".gmi"]
309 output = ".gmi"
310 template = ".gmi"
311 static_dir = "static"
312 output_dir = "public"
313
314 # Export an HTML version of the site
315 [[tasks]]
316 input = [".gmi"]
317 output = ".html"
318 template = ".gmi"
319 postprocess = "gmnitohtml"
320 static_dir = "static"
321 output_dir = "public.html"
322
323 The following configuration generates an HTML site from Markdown files
324 in the content directory and HTML templates in the templates directory.
325 This configuration makes use of the markdown(1) comand to convert Mark‐
326 down to HTML.
327
328 [[tasks]]
329 input_ext = [".md"]
330 output_ext = ".html"
331 template_ext = ".html"
332 preprocess.md = "markdown"
333 static_dir = "static"
334 output_dir = "public"
335
337 Templates have certain data and functions available to them.
338
339 TEMPLATE FUNCTIONS
340 All templates have the following functions available to them:
341
342 and args...
343 Returns the boolean AND of its arguments by returning the first
344 empty argument or the last argument, that is, "and x y" behaves as
345 "if x then y else x". All the arguments are evaluated.
346
347 call function, args...
348 Returns the result of calling the first argument, which must be a
349 function, with the remaining arguments as parameters. Thus "call
350 .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where Y is a func-val‐
351 ued field, map entry, or the like. The first argument must be the
352 result of an evaluation that yields a value of function type (as
353 distinct from a predefined function such as print). The function
354 must return either one or two result values, the second of which is
355 of type error. If the arguments don't match the function or the re‐
356 turned error value is non-nil, execution stops.
357
358 eq arg1, arg2
359 Returns the boolean truth of arg1 == arg2.
360
361 ge arg1, arg2
362 Returns the boolean truth of arg1 >= arg2.
363
364 gt arg1, arg2
365 Returns the boolean truth of arg1 > arg2.
366
367 html args...
368 Returns the escaped HTML equivalent of the textual representation
369 of its arguments. This function is unavailable in HTML templates,
370 with a few exceptions.
371
372 index collection, args...
373 Returns the result of indexing its first argument by the following
374 arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
375 indexed item must be a map, slice, or array.
376
377 js args...
378 Returns the escaped JavaScript equivalent of the textual represen‐
379 tation of its arguments.
380
381 le arg1, arg2
382 Returns the boolean truth of arg1 <= arg2.
383
384 len list
385 Returns the integer length of its argument.
386
387 lt arg1, arg2
388 Returns the boolean truth of arg1 < arg2.
389
390 ne arg1, arg2
391 Returns the boolean truth of arg1 != arg2.
392
393 not arg
394 Returns the boolean negation of its single argument.
395
396 or args...
397 Returns the boolean OR of its arguments by returning the first non-
398 empty argument or the last argument, that is, "or x y" behaves as
399 "if x then x else y". All the arguments are evaluated.
400
401 partial name, data
402 Executes the named partial template with the provided data. See
403 PARTIAL TEMPLATES.
404
405 Example:
406
407 {{ partial "header.gmi" . }}
408
409 path.Base path
410 Returns the last element of path.
411
412 path.Clean path
413 Returns the shortest path name equivalent to path.
414
415 path.Dir path
416 Returns all but the last element of path, typically the path's di‐
417 rectory.
418
419 path.Ext path
420 Returns the filename extension used by path.
421
422 path.Join elem...
423 Joins any number of path elements into a single path.
424
425 print args...
426 Formats using the default formats for its operands and returns the
427 resulting string. Spaces are added between operands when neither is
428 a string.
429
430 printf format, args...
431 Formats according to a format specifier and returns the resulting
432 string.
433
434 println args...
435 Formats using the default formats for its operands and returns the
436 resulting string. Spaces are always added between operands and a
437 newline is appended.
438
439 reverse list
440 Returns a reversed copy of the provided slice or array.
441
442 safeCSS css
443 Encapsulates known safe CSS content.
444
445 safeHTML html
446 Encapsulates a known safe HTML document fragment.
447
448 safeHTMLAttr attr
449 Encapsulates an HTML attribute from a trusted source.
450
451 safeJS js
452 Encapsulates a known safe JavaScript expression.
453
454 safeURL url
455 Encapsulates a known safe URL or URL substring.
456
457 site
458 Returns site metadata (see SITE METADATA).
459
460 slice list, args...
461 slice returns the result of slicing its first argument by the re‐
462 maining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2],
463 while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3"
464 is x[1:2:3]. The first argument must be a string, slice, or array.
465
466 strings.Count string, substr
467 Counts the number of non-overlapping instances of substr in string.
468 If substr is an empty string, Count returns 1 + the number of Uni‐
469 code code points in string.
470
471 strings.HasPrefix string, prefix
472 Reports whether string begins with prefix.
473
474 strings.HasSuffix string, suffix
475 Reports whether string ends with suffix.
476
477 strings.Join elems, sep
478 Concatenates the elements of its first argument to create a single
479 string. The separator string sep is placed between elements in the
480 resulting string.
481
482 strings.Repeat string, count
483 Returns a new string consisting of count copies of string.
484
485 It panics if count is negative or if the result of (len(string) *
486 count) overflows.
487
488 strings.Replace string, old, new, n
489 Returns a copy of string with the first n non-overlapping instances
490 of old replaced by new. If old is empty, it matches at the begin‐
491 ning of the string and after each UTF-8 sequence, yielding up to
492 k+1 replacements for a k-rune string. If n < 0, there is no limit
493 on the number of replacements.
494
495 strings.ReplaceAll string, old, new
496 Returns a copy of string with all non-overlapping instances of old
497 replaced by new. If old is empty, it matches at the beginning of
498 the string and after each UTF-8 sequence, yielding up to k+1 re‐
499 placements for a k-rune string.
500
501 strings.Split string, sep
502 Slices string into all substrings separated by sep and returns a
503 slice of the substrings between those separators.
504
505 If string does not contain sep and sep is not empty, Split returns
506 a slice of length 1 whose only element is string.
507
508 If sep is empty, Split splits after each UTF-8 sequence. If both
509 string and sep are empty, Split returns an empty slice.
510
511 strings.Title string
512 Returns a copy of the string with all Unicode letters that begin
513 words mapped to their Unicode title case.
514
515 BUG: The rule Title uses for word boundaries does not handle Uni‐
516 code punctuation properly.
517
518 strings.ToLower string
519 Returns string with all Unicode letters mapped to their lower case.
520
521 strings.ToUpper string
522 Returns string with all Unicode letters mapped to their upper case.
523
524 strings.Trim string, cutset
525 Returns a slice of string with all leading and trailing Unicode
526 code points contained in cutset removed.
527
528 strings.TrimLeft string, cutset
529 Returns a slice of string with all leading Unicode code points con‐
530 tained in cutset removed.
531
532 To remove a prefix, use strings.TrimPrefix instead.
533
534 strings.TrimPrefix string, prefix
535 Returns string without the provided leading prefix string. If
536 string doesn't start with prefix, it is returned unchanged.
537
538 strings.TrimRight string, cutset
539 Returns a slice of string with all trailing Unicode code points
540 contained in cutset removed.
541
542 To remove a suffix, use strings.TrimSuffix instead.
543
544 strings.TrimSpace string
545 Returns a slice of string with all leading and trailing white space
546 removed, as defined by Unicode.
547
548 strings.TrimSuffix string, suffix
549 Returns string without the provided trailing suffix string. If
550 string doesn't end with suffix, it is returned unchanged.
551
552 urlquery args...
553 Returns the escaped value of the textual representation of its ar‐
554 guments in a form suitable for embedding in a URL query. This func‐
555 tion is unavailable in HTML templates, with a few exceptions.
556
557 SITE METADATA
558 Site metadata contains the following data:
559
560 package main
561
562 import (
563 "fmt" "path"
564 )
565
566 func main() {
567 fmt.Println(path.Join("https://example.com", "hello-world"))
568 }
569
570 ┌─────────┬────────────────────────┐
571 │Variable │ Description │
572 ├─────────┼────────────────────────┤
573 │Title │ The title of the site. │
574 ├─────────┼────────────────────────┤
575 │URLs │ The URLs of the site. │
576 └─────────┴────────────────────────┘
577 To configure these variables, see CONFIGURATION.
578
579 PAGE TEMPLATES
580 Page templates are provided with the following data:
581
582 ┌──────────┬────────────────────────────┐
583 │Variable │ Description │
584 ├──────────┼────────────────────────────┤
585 │Title │ The title of the page │
586 ├──────────┼────────────────────────────┤
587 │Date │ The date of the page │
588 ├──────────┼────────────────────────────┤
589 │Weight │ The weight of the page │
590 ├──────────┼────────────────────────────┤
591 │Permalink │ The permanent link to this │
592 │ │ page │
593 ├──────────┼────────────────────────────┤
594 │FilePath │ The path of the page file │
595 │ │ relative to the content │
596 │ │ directory │
597 ├──────────┼────────────────────────────┤
598 │Content │ The contents of the page │
599 ├──────────┼────────────────────────────┤
600 │Params │ Extra parameters specified │
601 │ │ in frontmatter │
602 ├──────────┼────────────────────────────┤
603 │Prev │ The previous page in this │
604 │ │ directory │
605 ├──────────┼────────────────────────────┤
606 │Next │ The next page in this di‐ │
607 │ │ rectory │
608 └──────────┴────────────────────────────┘
609
610 INDEX TEMPLATES
611 Index templates are provided with all the data that page templates are
612 provided, plus the following data:
613
614 ┌─────────┬───────────────────────────┐
615 │Variable │ Description │
616 ├─────────┼───────────────────────────┤
617 │Pages │ List of pages in this di‐ │
618 │ │ rectory │
619 ├─────────┼───────────────────────────┤
620 │Dirs │ List of subdirectories │
621 └─────────┴───────────────────────────┘
622
623 FEED TEMPLATES
624 Feed templates are provided with the following data:
625
626 ┌──────────┬────────────────────────────┐
627 │Variable │ Description │
628 ├──────────┼────────────────────────────┤
629 │Title │ Title of the feed │
630 ├──────────┼────────────────────────────┤
631 │Permalink │ The permanent link to the │
632 │ │ feed directory │
633 ├──────────┼────────────────────────────┤
634 │Entries │ List of pages in this feed │
635 └──────────┴────────────────────────────┘
636
637 PARTIAL TEMPLATES
638 Partial templates can be specified in the templates/_partials direc‐
639 tory. Partial templates can be executed from any other template with
640 the partial function. See TEMPLATE FUNCTIONS.
641
642
643
644 2021-07-22 kiln(1)