1kiln(1) General Commands Manual kiln(1)
2
6 kiln - a simple static site generator
7
9 kiln build [-c config]
10 kiln new path
12 kiln version
14
16 kiln build builds a kiln site.
17 kiln new creates a new kiln site at the given path.
19 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 The following directories are common to all tasks:
34 ┌───────────┬─────────────────────┐
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 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 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 Pages with the name "_index" are index pages and are treated specially.
58 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 Example:
65 ---
67 title: Page title
68 date: 2021-04-24
69 params:
70 custom: value
71 ---
72 Page content
74 The following keys are supported:
76 title
78 The title of the page.
79 Example:
81 ---
83 title: My first post
84 ---
85 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 Example:
91 ---
93 date: 2021-05-21
94 ---
95 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 Example:
102 ---
104 weight: 1
105 ---
106 params
108 Specifies extra parameters to be provided to templates.
109 Example:
111 ---
113 params:
114 key: value
115 ---
116 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 ┌──────────┬──────────────────────────┐
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 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 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 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 The configuration file uses the TOML format.
160 The following keys are supported:
162 ┌──────┬─────────────────────┐
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 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 Feeds are written to the output directory plus the feed directory plus
180 "atom.xml".
181 Example feed configuration:
183 # This will generate a feed which will be written to public/blog/atom.xml
185 [feeds]
186 "/blog/" = "My blog"
187 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 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 [permalinks]
201 "/blog/" = "/{{ .Date.Format `2006/01/02` }}/{{ path.Base .Permalink }}"
202 For more information on templates, see TEMPLATES.
204 TASKS
206 Tasks can be specified in the [[tasks]] array of tables.
207 The following configuration options are supported per task:
209 input
211 A list of input file extensions. Files in the content directory
212 with a matching extension will be processed.
213 Example:
215 [[tasks]]
217 input = [".gmi", ".md"]
218 output
220 The output file extension. Files written to the output directory
221 will use this extension.
222 Example:
224 [[tasks]]
226 output = ".html"
227 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 Example:
234 [[tasks]]
236 template = ".gmi"
237 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 Example:
245 [[tasks]]
247 input = [".gmi", ".md"]
248 output = ".html"
249 preprocess.gmi = "gmnitohtml"
250 preprocess.md = "mdtohtml"
251 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 Example:
259 [[tasks]]
261 input = [".gmi"]
262 output = ".html"
263 template = ".gmi"
264 postprocess = "gmnitohtml"
265 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 Example:
273 [[tasks]]
275 static_dir = "static"
276 output_dir
278 Specifies the directory to which output files will be written.
279 Example:
281 [[tasks]]
283 output_dir = "public"
284 ugly_urls
286 Specifies whether page permalinks will contain file extensions. By
287 default, clean URLs without any extension are used.
288 Example:
290 [[tasks]]
292 ugly_urls = true
293 The following configuration builds a simple Gemini site.
295 [[tasks]]
297 input = [".gmi"]
298 output = ".gmi"
299 template = ".gmi"
300 output_dir = "public"
301 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 # Build the site
307 [[tasks]]
308 input = [".gmi"]
309 output = ".gmi"
310 template = ".gmi"
311 static_dir = "static"
312 output_dir = "public"
313 # 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 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 [[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 TEMPLATE FUNCTIONS
340 All templates have the following functions available to them:
341 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 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 eq arg1, arg2
359 Returns the boolean truth of arg1 == arg2.
360 ge arg1, arg2
362 Returns the boolean truth of arg1 >= arg2.
363 gt arg1, arg2
365 Returns the boolean truth of arg1 > arg2.
366 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 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 js args...
378 Returns the escaped JavaScript equivalent of the textual represen‐
379 tation of its arguments.
380 le arg1, arg2
382 Returns the boolean truth of arg1 <= arg2.
383 len list
385 Returns the integer length of its argument.
386 lt arg1, arg2
388 Returns the boolean truth of arg1 < arg2.
389 ne arg1, arg2
391 Returns the boolean truth of arg1 != arg2.
392 not arg
394 Returns the boolean negation of its single argument.
395 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 partial name, data
402 Executes the named partial template with the provided data. See
403 PARTIAL TEMPLATES.
404 Example:
406 {{ partial "header.gmi" . }}
408 path.Base path
410 Returns the last element of path.
411 path.Clean path
413 Returns the shortest path name equivalent to path.
414 path.Dir path
416 Returns all but the last element of path, typically the path's di‐
417 rectory.
418 path.Ext path
420 Returns the filename extension used by path.
421 path.Join elem...
423 Joins any number of path elements into a single path.
424 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 printf format, args...
431 Formats according to a format specifier and returns the resulting
432 string.
433 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 reverse list
440 Returns a reversed copy of the provided slice or array.
441 safeCSS css
443 Encapsulates known safe CSS content.
444 safeHTML html
446 Encapsulates a known safe HTML document fragment.
447 safeHTMLAttr attr
449 Encapsulates an HTML attribute from a trusted source.
450 safeJS js
452 Encapsulates a known safe JavaScript expression.
453 safeURL url
455 Encapsulates a known safe URL or URL substring.
456 site
458 Returns site metadata (see SITE METADATA).
459 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 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 strings.HasPrefix string, prefix
472 Reports whether string begins with prefix.
473 strings.HasSuffix string, suffix
475 Reports whether string ends with suffix.
476 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 strings.Repeat string, count
483 Returns a new string consisting of count copies of string.
484 It panics if count is negative or if the result of (len(string) *
486 count) overflows.
487 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 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 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 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 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 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 BUG: The rule Title uses for word boundaries does not handle Uni‐
516 code punctuation properly.
517 strings.ToLower string
519 Returns string with all Unicode letters mapped to their lower case.
520 strings.ToUpper string
522 Returns string with all Unicode letters mapped to their upper case.
523 strings.Trim string, cutset
525 Returns a slice of string with all leading and trailing Unicode
526 code points contained in cutset removed.
527 strings.TrimLeft string, cutset
529 Returns a slice of string with all leading Unicode code points con‐
530 tained in cutset removed.
531 To remove a prefix, use strings.TrimPrefix instead.
533 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 strings.TrimRight string, cutset
539 Returns a slice of string with all trailing Unicode code points
540 contained in cutset removed.
541 To remove a suffix, use strings.TrimSuffix instead.
543 strings.TrimSpace string
545 Returns a slice of string with all leading and trailing white space
546 removed, as defined by Unicode.
547 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 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 SITE METADATA
558 Site metadata contains the following data:
559 package main
561 import (
563 "fmt" "path"
564 )
565 func main() {
567 fmt.Println(path.Join("https://example.com", "hello-world"))
568 }
569 ┌─────────┬────────────────────────┐
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 PAGE TEMPLATES
580 Page templates are provided with the following data:
581 ┌──────────┬────────────────────────────┐
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 INDEX TEMPLATES
611 Index templates are provided with all the data that page templates are
612 provided, plus the following data:
613 ┌─────────┬───────────────────────────┐
615 │Variable │ Description │
616 ├─────────┼───────────────────────────┤
617 │Pages │ List of pages in this di‐ │
618 │ │ rectory │
619 ├─────────┼───────────────────────────┤
620 │Dirs │ List of subdirectories │
621 └─────────┴───────────────────────────┘
622 FEED TEMPLATES
624 Feed templates are provided with the following data:
625 ┌──────────┬────────────────────────────┐
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 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 2021-07-22 kiln(1)