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 The basic unit of a kiln site is the page. Each page either represents
43 a content file or a subdirectory containing other pages. Pages may be
44 preprocessed, run through templates, and postprocessed (in that order).
45 Each operation takes the output of the last operation as input.
46
48 The content directory contains site content files which can be nested
49 in subdirectories. Any file or directory in the content directory whose
50 name begins with "_" will be ignored, with the exception of files with
51 the name "_index" (e.g. "_index.gmi").
52 Content files can specify dates in their filenames. For example, the
54 file content/2020-11-20-Hello-world.gmi will result in a page with a
55 path of /Hello-world/ and a date of November 20, 2020.
56 Files with the name "_index" are treated specially. They can be used to
58 provide frontmatter and content for the parent directory which will
59 otherwise have none. If an "_index" file is present in a directory, an
60 index page (e.g. "index.gmi") for that directory will be generated and
61 written to the output directory.
62 FRONTMATTER
64 Pages can specify additional metadata in frontmatter. Frontmatter is
65 delimited by "---" and is specified in YAML. Newlines after the closing
66 delimiter are removed from the content.
67 Example:
69 ---
71 title: Page title
72 date: 2021-04-24
73 params:
74 key: value
75 ---
76 Page content
78 The following keys are supported:
80 title
82 The title of the page.
83 Example:
85 ---
87 title: My first post
88 ---
89 date
91 The date of the page. Pages are sorted by date in reverse order, so
92 newer pages will be placed above older pages.
93 Example:
95 ---
97 date: 2021-05-21
98 ---
99 weight
101 The weight of the page. Pages are sorted by weight in increasing
102 order, so pages with a smaller weight will be placed above pages
103 with a larger weight.
104 Example:
106 ---
108 weight: 1
109 ---
110 outputs
112 Optionally specifies a list of tasks that can build this page. De‐
113 faults to all tasks.
114 Example:
116 ---
118 outputs: ["Gemini", "HTTPS"]
119 ---
120 ---
122 outputs: [] # Excluded from all tasks
123 ---
124 params
126 Specifies extra parameters to be provided to templates.
127 Example:
129 ---
131 params:
132 key: value
133 ---
134 SORTING
136 Pages are sorted automatically. Pages are first ordered by weight in
137 increasing order, then by date from newest to oldest, and then by file‐
138 name in alphabetical order.
139
141 The templates directory contains templates for use when building the
142 site. Templates use the Go templating language. The following templates
143 are supported:
144 ┌──────────┬──────────────────────────┐
146 │Template │ Description │
147 ├──────────┼──────────────────────────┤
148 │page.ext │ Page template │
149 ├──────────┼──────────────────────────┤
150 │index.ext │ Directory index template │
151 ├──────────┼──────────────────────────┤
152 │base.ext │ Base template from which │
153 │ │ the page and index tem‐ │
154 │ │ plates inherit │
155 ├──────────┼──────────────────────────┤
156 │atom.xml │ Atom feed template │
157 └──────────┴──────────────────────────┘
158 The extension of page and index templates is configurable and will re‐
159 place ".ext" above. See CONFIGURATION.
160 The scope of a template is limited by the directory it is placed in.
162 For example, a template in the templates/blog directory will only apply
163 to files in content/blog.
164 Fallback templates can be specified in the templates/_default direc‐
166 tory. These templates will apply to any directory which does not have
167 its own templates specified in the template directory.
168 For more information on the Go templating language, see
170 https://golang.org/pkg/text/template/.
171
173 By default, kiln looks for a configuration file named "config.toml". An
174 alternative configuration file can be specified with the -c flag. See
175 OPTIONS.
176 The configuration file uses the TOML format.
178 The following keys are supported:
180 ┌───────┬────────────────────────┐
182 │Key │ Description │
183 ├───────┼────────────────────────┤
184 │title │ Site title │
185 ├───────┼────────────────────────┤
186 │params │ Extra parameters made │
187 │ │ available to templates │
188 └───────┴────────────────────────┘
189 PERMALINKS
191 Permalinks can be used to rewrite page paths. Permalinks are specified
192 in the [permalinks] table of the configuration file. Keys denote a path
193 to a directory, and values use the Go templating language to rewrite
194 the final path of pages in that directory. The templates have the same
195 data that page templates have available to them (see PAGE TEMPLATES).
196 The following configuration will rewrite the paths of pages in the con‐
198 tent/blog directory to /YYYY/MM/DD/slug. For example, the file con‐
199 tent/blog/2021-05-12-hello-world.gmi will have a path of
200 /2021/05/12/hello-world/.
201 [permalinks]
203 "/blog/" = "/{{ .Date.Format `2006/01/02` }}/{{ path.Base .Path }}"
204 For more information on templates, see TEMPLATES.
206 TASKS
208 Tasks can be specified in the [[tasks]] array of tables.
209 The following configuration options are supported per task:
211 name
213 An optional name for the task.
214 Example:
216 [[tasks]]
218 name = "Gemini"
219 [[tasks]]
221 name = "HTML export"
222 input
224 A list of input file extensions. Files in the content directory
225 with a matching extension will be processed.
226 Example:
228 [[tasks]]
230 input = [".gmi", ".md"]
231 output
233 The output file extension. Files written to the output directory
234 will use this extension.
235 Example:
237 [[tasks]]
239 output = ".html"
240 template
242 The template file extension. Templates with this file extension
243 will be used to format the content. If unset, no templates will be
244 used.
245 Example:
247 [[tasks]]
249 template = ".gmi"
250 preprocess
252 Maps file extensions to preprocess commands. Preprocess commands
253 will run before templating. The commands will be provided the con‐
254 tent of the page as standard input and should write the processed
255 content to standard output.
256 Example:
258 [[tasks]]
260 input = [".gmi", ".md"]
261 output = ".html"
262 preprocess.gmi = "gmnitohtml"
263 preprocess.md = "mdtohtml"
264 postprocess
266 Specifies a command which will run after templating and before con‐
267 tent is written to the output directory. It will be provided the
268 content of the page as standard input and should write the pro‐
269 cessed content to standard output.
270 Example:
272 [[tasks]]
274 input = [".gmi"]
275 output = ".html"
276 template = ".gmi"
277 postprocess = "gmnitohtml"
278 static_dir
280 Specifies a directory from which to read static content. All files
281 in this directory will be copied to the output directory without
282 modificiation. Static assets like images should be stored in this
283 directory. If unset, no static content directory will be used.
284 Example:
286 [[tasks]]
288 static_dir = "static"
289 output_dir
291 Specifies the directory to which output files will be written.
292 Example:
294 [[tasks]]
296 output_dir = "public"
297 url
299 The base URL to use for page URLs. The base URL should not have
300 trailing forward slashes.
301 ugly_urls
303 Specifies whether page paths will contain file extensions. By de‐
304 fault, clean paths without any extension are used.
305 Example:
307 [[tasks]]
309 ugly_urls = true
310 The following configuration builds a simple Gemini site.
312 [[tasks]]
314 input = [".gmi"]
315 output = ".gmi"
316 template = ".gmi"
317 output_dir = "public"
318 The following configuration generates a Gemini text site and also ex‐
320 ports an HTML version of the site. This configuration makes use of the
321 gmnitohtml(1) command to convert Gemini text to HTML.
322 # Build the site
324 [[tasks]]
325 input = [".gmi"]
326 output = ".gmi"
327 template = ".gmi"
328 static_dir = "static"
329 output_dir = "public"
330 # Export an HTML version of the site
332 [[tasks]]
333 input = [".gmi"]
334 output = ".html"
335 template = ".gmi"
336 postprocess = "gmnitohtml"
337 static_dir = "static"
338 output_dir = "public_html"
339 The following configuration generates an HTML site from Markdown and
341 Gemini text files in the content directory and HTML templates in the
342 templates directory. This configuration makes use of the mdtohtml(1)
343 command to convert Markdown to HTML, and the gmnitohtml(1) command to
344 convert Gemini text to HTML.
345 [[tasks]]
347 input = [".md", ".gmi"]
348 output = ".html"
349 template = ".html"
350 preprocess.md = "mdtohtml"
351 preprocess.gmi = "gmnitohtml"
352 static_dir = "static"
353 output_dir = "public"
354 FEEDS
356 Feeds can be specified in the [[tasks.feeds]] array of tables. Multiple
357 feeds can be specified per task.
358 Example feed configuration:
360 [[tasks]]
362 # ...
363 # This generates a feed for the files in content/blog
365 # and writes it to blog/atom.xml (relative to the output directory)
366 [[tasks.feeds]]
367 input_dir = "blog"
368 title = "My Blog"
369 template = "atom.xml"
370 output = "blog/atom.xml"
371 # You can generate multiple feeds per task
373 # The generated feed can be written anywhere
374 # Here it is written to feed.xml (relative to the output directory)
375 [[tasks.feeds]]
376 input_dir = "blog"
377 title = "My Blog"
378 template = "custom_feed.xml"
379 output = "feed.xml"
380 input_dir
382 the content folder with which to populate the feed
383 title
385 the title of the feed, accessible via {{ .Title }} in the feed tem‐
386 plate
387 template
389 the template to use for the feed
390 output
392 the output path for the rendered feed
393
395 Templates have certain data and functions available to them.
396 SITE METADATA
398 Site metadata contains the following data:
399 Title
401 The title of the site.
402 Params
404 Extra parameters specified in configuration.
405 Generated
407 Site generation time.
408 Root
410 The root page of the site.
411 Site metadata can be accessed from templates with the site function.
413 See TEMPLATE FUNCTIONS.
414 To configure these variables, see CONFIGURATION.
416 PAGE TEMPLATES
418 Page and index templates are provided with the following data:
419 Title
421 The title of the page
422 Date
424 The date of the page
425 Weight
427 The weight of the page
428 Path
430 The path to the page
431 URL
433 The URL of the page. If no base URL is configured, it is equivalent
434 to Path.
435 FilePath
437 The path of the page file or directory relative to the content di‐
438 rectory
439 Content
441 The contents of the page
442 Params
444 Extra parameters specified in frontmatter
445 Prev
447 The previous page in sorted order
448 Next
450 The next page in sorted order
451 Pages
453 List of pages in this directory
454 Dirs
456 List of subdirectories in this directory
457 FEED TEMPLATES
459 Feed templates are provided with the following data:
460 Title
462 Title of the feed
463 Path
465 The path to the feed directory
466 URL
468 The URL of the feed directory
469 Pages
471 List of pages in this feed
472 PARTIAL TEMPLATES
474 Partial templates can be placed in the templates/_partials directory.
475 Partial templates can be executed from any other template with the par‐
476 tial function. See TEMPLATE FUNCTIONS.
477 TEMPLATE FUNCTIONS
479 All templates have the following functions available to them:
480 and args...
482 Returns the boolean AND of its arguments by returning the first
483 empty argument or the last argument, that is, "and x y" behaves as
484 "if x then y else x". All the arguments are evaluated.
485 call function, args...
487 Returns the result of calling the first argument, which must be a
488 function, with the remaining arguments as parameters. Thus "call
489 .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where Y is a func-val‐
490 ued field, map entry, or the like. The first argument must be the
491 result of an evaluation that yields a value of function type (as
492 distinct from a predefined function such as print). The function
493 must return either one or two result values, the second of which is
494 of type error. If the arguments don't match the function or the re‐
495 turned error value is non-nil, execution stops.
496 eq arg1, arg2
498 Returns the boolean truth of arg1 == arg2.
499 exec command, input
501 Executes the given external command with input provided as standard
502 input. Returns its standard output.
503 ge arg1, arg2
505 Returns the boolean truth of arg1 >= arg2.
506 gt arg1, arg2
508 Returns the boolean truth of arg1 > arg2.
509 html args...
511 Returns the escaped HTML equivalent of the textual representation
512 of its arguments. This function is unavailable in HTML templates,
513 with a few exceptions.
514 index collection, args...
516 Returns the result of indexing its first argument by the following
517 arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
518 indexed item must be a map, slice, or array.
519 js args...
521 Returns the escaped JavaScript equivalent of the textual represen‐
522 tation of its arguments.
523 le arg1, arg2
525 Returns the boolean truth of arg1 <= arg2.
526 len list
528 Returns the integer length of its argument.
529 lt arg1, arg2
531 Returns the boolean truth of arg1 < arg2.
532 ne arg1, arg2
534 Returns the boolean truth of arg1 != arg2.
535 not arg
537 Returns the boolean negation of its single argument.
538 or args...
540 Returns the boolean OR of its arguments by returning the first non-
541 empty argument or the last argument, that is, "or x y" behaves as
542 "if x then x else y". All the arguments are evaluated.
543 partial name, data
545 Executes the named partial template with the provided data. See
546 PARTIAL TEMPLATES.
547 Example:
549 {{ partial "header.gmi" . }}
551 path.Base path
553 Returns the last element of path.
554 path.Clean path
556 Returns the shortest path name equivalent to path.
557 path.Dir path
559 Returns all but the last element of path, typically the path's di‐
560 rectory.
561 path.Ext path
563 Returns the filename extension used by path.
564 path.Join elem...
566 Joins any number of path elements into a single path.
567 print args...
569 Formats using the default formats for its operands and returns the
570 resulting string. Spaces are added between operands when neither is
571 a string.
572 printf format, args...
574 Formats according to a format specifier and returns the resulting
575 string.
576 println args...
578 Formats using the default formats for its operands and returns the
579 resulting string. Spaces are always added between operands and a
580 newline is appended.
581 reverse list
583 Returns a reversed copy of the provided slice or array.
584 safeCSS css
586 Encapsulates known safe CSS content.
587 safeHTML html
589 Encapsulates a known safe HTML document fragment.
590 safeHTMLAttr attr
592 Encapsulates an HTML attribute from a trusted source.
593 safeJS js
595 Encapsulates a known safe JavaScript expression.
596 safeURL url
598 Encapsulates a known safe URL or URL substring.
599 site
601 Returns site metadata (see SITE METADATA).
602 slice list, args...
604 slice returns the result of slicing its first argument by the re‐
605 maining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2],
606 while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3"
607 is x[1:2:3]. The first argument must be a string, slice, or array.
608 strings.Count string, substr
610 Counts the number of non-overlapping instances of substr in string.
611 If substr is an empty string, Count returns 1 + the number of Uni‐
612 code code points in string.
613 strings.HasPrefix string, prefix
615 Reports whether string begins with prefix.
616 strings.HasSuffix string, suffix
618 Reports whether string ends with suffix.
619 strings.Join elems, sep
621 Concatenates the elements of its first argument to create a single
622 string. The separator string sep is placed between elements in the
623 resulting string.
624 strings.Repeat string, count
626 Returns a new string consisting of count copies of string.
627 It panics if count is negative or if the result of (len(string) *
629 count) overflows.
630 strings.Replace string, old, new, n
632 Returns a copy of string with the first n non-overlapping instances
633 of old replaced by new. If old is empty, it matches at the begin‐
634 ning of the string and after each UTF-8 sequence, yielding up to
635 k+1 replacements for a k-rune string. If n < 0, there is no limit
636 on the number of replacements.
637 strings.ReplaceAll string, old, new
639 Returns a copy of string with all non-overlapping instances of old
640 replaced by new. If old is empty, it matches at the beginning of
641 the string and after each UTF-8 sequence, yielding up to k+1 re‐
642 placements for a k-rune string.
643 strings.Split string, sep
645 Slices string into all substrings separated by sep and returns a
646 slice of the substrings between those separators.
647 If string does not contain sep and sep is not empty, Split returns
649 a slice of length 1 whose only element is string.
650 If sep is empty, Split splits after each UTF-8 sequence. If both
652 string and sep are empty, Split returns an empty slice.
653 strings.Title string
655 Returns a copy of the string with all Unicode letters that begin
656 words mapped to their Unicode title case.
657 BUG: The rule Title uses for word boundaries does not handle Uni‐
659 code punctuation properly.
660 strings.ToLower string
662 Returns string with all Unicode letters mapped to their lower case.
663 strings.ToUpper string
665 Returns string with all Unicode letters mapped to their upper case.
666 strings.Trim string, cutset
668 Returns a slice of string with all leading and trailing Unicode
669 code points contained in cutset removed.
670 strings.TrimLeft string, cutset
672 Returns a slice of string with all leading Unicode code points con‐
673 tained in cutset removed.
674 To remove a prefix, use strings.TrimPrefix instead.
676 strings.TrimPrefix string, prefix
678 Returns string without the provided leading prefix string. If
679 string doesn't start with prefix, it is returned unchanged.
680 strings.TrimRight string, cutset
682 Returns a slice of string with all trailing Unicode code points
683 contained in cutset removed.
684 To remove a suffix, use strings.TrimSuffix instead.
686 strings.TrimSpace string
688 Returns a slice of string with all leading and trailing white space
689 removed, as defined by Unicode.
690 strings.TrimSuffix string, suffix
692 Returns string without the provided trailing suffix string. If
693 string doesn't end with suffix, it is returned unchanged.
694 urlquery args...
696 Returns the escaped value of the textual representation of its ar‐
697 guments in a form suitable for embedding in a URL query. This func‐
698 tion is unavailable in HTML templates, with a few exceptions.
699 2022-07-03 kiln(1)