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
14 kiln build builds a kiln site.
15 kiln new creates a new kiln site at the given path.
17
19 kiln build
20 -c config
21 Specifies the configuration file to use. Defaults to "config.toml".
22
24 A kiln site is built in one or more steps called tasks. Tasks read con‐
25 tent from the content directory, process the content, and write the
26 content to the output directory. Tasks can also be configured to copy
27 static content to the output directory.
28 The following directories are common to all tasks:
30 ┌───────────┬─────────────────────┐
32 │Directory │ Description │
33 ├───────────┼─────────────────────┤
34 │content/ │ Content directory │
35 ├───────────┼─────────────────────┤
36 │templates/ │ Templates directory │
37 └───────────┴─────────────────────┘
38 The basic unit of a kiln site is the page. Each page either represents
39 a content file or a subdirectory containing other pages. Pages may be
40 preprocessed, run through templates, and postprocessed (in that order).
41 Each operation takes the output of the last operation as input.
42
44 The content directory contains site content files which can be nested
45 in subdirectories. Any file or directory in the content directory whose
46 name begins with "_" will be ignored, with the exception of files with
47 the name "_index" (e.g. "_index.gmi").
48 Content files can specify dates in their filenames. For example, the
50 file content/2020-11-20-Hello-world.gmi will result in a page with a
51 path of /Hello-world/ and a date of November 20, 2020.
52 Files with the name "_index" are treated specially. They can be used to
54 provide frontmatter and content for the parent directory which will
55 otherwise have none. If an "_index" file is present in a directory, an
56 index page (e.g. "index.gmi") for that directory will be generated and
57 written to the output directory.
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 key: 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 outputs
108 Optionally specifies a list of tasks that can build this page. De‐
109 faults to all tasks.
110 Example:
112 ---
114 outputs: ["Gemini", "HTTPS"]
115 ---
116 ---
118 outputs: [] # Excluded from all tasks
119 ---
120 template
122 Optionally specifies the name of the template to use when building
123 this page. If unspecified, defaults to "page" for regular pages and
124 "index" for index pages. The template is then found according to
125 TEMPLATE RESOLUTION.
126 Example:
128 ---
130 title: About me
131 template: about
132 ---
133 params
135 Specifies extra parameters to be provided to templates.
136 Example:
138 ---
140 params:
141 key: value
142 ---
143 SORTING
145 Pages are sorted automatically. Pages are first ordered by weight in
146 increasing order, then by date from newest to oldest, and then by file‐
147 name in alphabetical order.
148
150 The templates directory contains templates for use when building the
151 site. Templates use the Go templating language. The following templates
152 are supported:
153 ┌──────────┬──────────────────────────┐
155 │Template │ Description │
156 ├──────────┼──────────────────────────┤
157 │page.ext │ Page template │
158 ├──────────┼──────────────────────────┤
159 │index.ext │ Directory index template │
160 ├──────────┼──────────────────────────┤
161 │base.ext │ Base template from which │
162 │ │ the page and index tem‐ │
163 │ │ plates inherit │
164 ├──────────┼──────────────────────────┤
165 │atom.xml │ Atom feed template │
166 └──────────┴──────────────────────────┘
167 The extension of page and index templates is configurable and will re‐
168 place ".ext" above. See CONFIGURATION.
169 For more information on the Go templating language, see
171 https://golang.org/pkg/text/template/.
172 PAGE AND INDEX TEMPLATES
174 The content for page and index templates can be accessed using the
175 .Content page variable. For example:
176 page header
178 {{ .Content }}
179 page footer
180 Other page variables are documented in PAGE VARIABLES.
182 In HTML templates, page content is escaped by default. If the content
184 is known to be safe, it must be marked as safe to avoid escaping. For
185 example:
186 <body>
188 {{ .Content | safeHTML }}
189 </body>
190 See TEMPLATE FUNCTIONS for more information.
192 BASE TEMPLATES
194 Base templates are inherited only by page and index templates. Base
195 templates generally define at least one block which can be customized
196 by page and index templates, according to the Go templating language.
197 For example, the base template could contain:
199 {{ block "body" . }}
201 Blocks can have default content
202 {{ end }}
203 {{ block "extra_content" . }}{{ end }}
204 The page and index templates can then customize these blocks, for exam‐
206 ple:
207 {{ define "body" }}
209 Body goes here
210 {{ end }}
211 TEMPLATE RESOLUTION
213 The scope of a template is limited by the directory it is placed in.
214 For example, a page template in the templates/blog/ directory will only
215 apply to files in content/blog/. A page template placed in templates/
216 will only apply to files in content/ and not its subdirectories.
217 Fallback templates can be specified in the templates/_default/ direc‐
219 tory. These templates will apply only when the required kind of tem‐
220 plate is not found in the template directory.
221 The template for a specific page can be overridden by setting the tem‐
223 plate key in the page's frontmatter. See FRONTMATTER for more details.
224 For example, the page file content/blog/my_first_post.gmi will be ren‐
226 dered with the template templates/blog/page.ext. If that template is
227 not found, it falls back to templates/_default/page.ext. If that tem‐
228 plate is also not found, then no template will be used.
229 Base templates also follow the same rules. For example, the index tem‐
231 plate templates/blog/index.ext inherits firstly from tem‐
232 plates/blog/base.ext, and then falls back to templates/_de‐
233 fault/base.ext if present.
234 There is no override mechanism for base templates.
236 PARTIAL TEMPLATES
238 Partial templates can be placed in the templates/_partials directory.
239 Partial templates can be executed from any other template using the
240 partial function. For example, a template could contain:
241 {{ partial "navbar.ext" . }}
243 Then templates/_partials/navbar.ext is executed. Since argument . is
245 provided, all data from the current context is provided. See TEMPLATE
246 FUNCTIONS for more information.
247 In HTML templates, the partial template content is escaped by default.
249 If the content is known to be safe, it must be marked as safe to avoid
250 escaping. For example:
251 <body>
253 {{ partial "navbar.ext" . | safeHTML }}
254 </body>
255 See TEMPLATE FUNCTIONS for more information.
257
259 By default, kiln looks for a configuration file named "config.toml". An
260 alternative configuration file can be specified with the -c flag. See
261 OPTIONS.
262 The configuration file uses the TOML format.
264 The following keys are supported:
266 ┌───────┬────────────────────────┐
268 │Key │ Description │
269 ├───────┼────────────────────────┤
270 │title │ Site title │
271 ├───────┼────────────────────────┤
272 │params │ Extra parameters made │
273 │ │ available to templates │
274 └───────┴────────────────────────┘
275 TASKS
277 Tasks can be specified in the [[tasks]] array of tables.
278 The following configuration options are supported per task:
280 name
282 An optional name for the task.
283 Example:
285 [[tasks]]
287 name = "Gemini"
288 [[tasks]]
290 name = "HTML export"
291 input
293 A list of input file extensions. Files in the content directory
294 with a matching extension will be processed.
295 Example:
297 [[tasks]]
299 input = [".gmi", ".md"]
300 output
302 The output file extension. Files written to the output directory
303 will use this extension.
304 Example:
306 [[tasks]]
308 output = ".html"
309 template
311 The template file extension. Templates with this file extension
312 will be used to format the content. If unset, no templates will be
313 used.
314 Example:
316 [[tasks]]
318 template = ".gmi"
319 preprocess
321 Maps file extensions to preprocess commands. Preprocess commands
322 will run before templating. The commands will be provided the con‐
323 tent of the page as standard input and should write the processed
324 content to standard output.
325 Example:
327 [[tasks]]
329 input = [".gmi", ".md"]
330 output = ".html"
331 preprocess.gmi = "gmnitohtml"
332 preprocess.md = "mdtohtml"
333 postprocess
335 Specifies a command which will run after templating and before con‐
336 tent is written to the output directory. It will be provided the
337 content of the page as standard input and should write the pro‐
338 cessed content to standard output.
339 Example:
341 [[tasks]]
343 input = [".gmi"]
344 output = ".html"
345 template = ".gmi"
346 postprocess = "gmnitohtml"
347 static_dir
349 Specifies a directory from which to read static content. All files
350 in this directory will be copied to the output directory without
351 modificiation. Static assets like images should be stored in this
352 directory. If unset, no static content directory will be used.
353 Example:
355 [[tasks]]
357 static_dir = "static"
358 output_dir
360 Specifies the directory to which output files will be written.
361 Example:
363 [[tasks]]
365 output_dir = "public"
366 url
368 The base URL to use for page URLs. The base URL should not have
369 trailing forward slashes.
370 ugly_urls
372 Specifies whether page paths will contain file extensions. By de‐
373 fault, clean paths without any extension are used.
374 Example:
376 [[tasks]]
378 ugly_urls = true
379 The following configuration builds a simple Gemini site.
381 [[tasks]]
383 input = [".gmi"]
384 output = ".gmi"
385 template = ".gmi"
386 output_dir = "public"
387 The following configuration generates a Gemini text site and also ex‐
389 ports an HTML version of the site. This configuration makes use of the
390 gmnitohtml(1) command to convert Gemini text to HTML.
391 # Build the site
393 [[tasks]]
394 input = [".gmi"]
395 output = ".gmi"
396 template = ".gmi"
397 static_dir = "static"
398 output_dir = "public"
399 # Export an HTML version of the site
401 [[tasks]]
402 input = [".gmi"]
403 output = ".html"
404 template = ".gmi"
405 postprocess = "gmnitohtml"
406 static_dir = "static"
407 output_dir = "public_html"
408 The following configuration generates an HTML site from Markdown and
410 Gemini text files in the content directory and HTML templates in the
411 templates directory. This configuration makes use of the mdtohtml(1)
412 command to convert Markdown to HTML, and the gmnitohtml(1) command to
413 convert Gemini text to HTML.
414 [[tasks]]
416 input = [".md", ".gmi"]
417 output = ".html"
418 template = ".html"
419 preprocess.md = "mdtohtml"
420 preprocess.gmi = "gmnitohtml"
421 static_dir = "static"
422 output_dir = "public"
423 PERMALINKS
425 Permalinks can be used to rewrite page paths. Permalinks are specified
426 in the [tasks.permalinks] table of the configuration file. Keys denote
427 a path to a directory, and values use the Go templating language to re‐
428 write the final path of pages in that directory. The templates have the
429 same data that page templates have available to them (see PAGE VARI‐
430 ABLES).
431 The following configuration will rewrite the paths of pages in the con‐
433 tent/blog directory to /YYYY/MM/DD/slug. For example, the file con‐
434 tent/blog/2021-05-12-hello-world.gmi will have a path of
435 /2021/05/12/hello-world/.
436 [[tasks]]
438 # ...
439 [tasks.permalinks]
441 "/blog/" = "/{{ .Date.Format `2006/01/02` }}/{{ path.Base .Path }}"
442 For more information on templates, see TEMPLATES.
444 FEEDS
446 Feeds can be specified in the [[tasks.feeds]] array of tables. Multiple
447 feeds can be specified per task.
448 Example feed configuration:
450 [[tasks]]
452 # ...
453 # This generates a feed for the files in content/blog
455 # and writes it to blog/atom.xml (relative to the output directory)
456 [[tasks.feeds]]
457 input_dir = "blog"
458 title = "My Blog"
459 template = "atom.xml"
460 output = "blog/atom.xml"
461 # You can generate multiple feeds per task
463 # The generated feed can be written anywhere
464 # Here it is written to feed.xml (relative to the output directory)
465 [[tasks.feeds]]
466 input_dir = "blog"
467 title = "My Blog"
468 template = "custom_feed.xml"
469 output = "feed.xml"
470 input_dir
472 the content folder with which to populate the feed
473 title
475 the title of the feed, accessible via {{ .Title }} in the feed tem‐
476 plate
477 template
479 the template to use for the feed
480 output
482 the output path for the rendered feed
483
485 Templates have certain data and functions available to them.
486 SITE VARIABLES
488 The following site-wide variables are available:
489 .Title
491 The title of the site.
492 .Params
494 Extra parameters specified in configuration.
495 .Generated
497 Site generation time.
498 .Root
500 The root page of the site. See PAGE VARIABLES.
501 Some of these variables are defined in your site's configuration. See
503 CONFIGURATION.
504 Site variables can be accessed from templates with the site function.
506 See TEMPLATE FUNCTIONS.
507 PAGE VARIABLES
509 The following page variables are available:
510 .Title
512 The title of the page
513 .Date
515 The date of the page
516 .Weight
518 The weight of the page
519 .Path
521 The path to the page
522 .URL
524 The URL of the page. If no base URL is configured, it is equivalent
525 to .Path.
526 .FilePath
528 The path of the page file or directory relative to the content di‐
529 rectory
530 .Content
532 The contents of the page
533 .Params
535 Extra parameters specified in frontmatter
536 .Prev
538 The previous page in sorted order
539 .Next
541 The next page in sorted order
542 .Pages
544 List of pages in this directory
545 .Dirs
547 List of subdirectories in this directory
548 Some of these variables are defined in page frontmatter. See FRONTMAT‐
550 TER.
551 Page variables can be accessed from page and index templates.
553 PAGE FUNCTIONS
555 The following page functions are available:
556 .GetPage path
558 Retrieves the page in this directory with the given path, which may
559 be relative or absolute.
560 Example:
562 {{/* Retrieve a directory relative to the root directory
564 and iterate over its pages */}}
565 {{ with site.Root.GetPage "/blog" }}
566 {{ range .Pages }}
567 {{ .Title }}
568 {{ end }}
569 {{ end }}
570 {{/* Retrieve a directory relative to the current directory
572 and iterate over its pages */}}
573 {{ with .GetPage "posts" }}
574 {{ range .Pages }}
575 {{ .Title }}
576 {{ end }}
577 {{ end }}
578 {{/* Retrieve a page relative to the current directory */}}
580 {{ with .GetPage "posts/hello-world.gmi" }}
581 {{ .Title }}
582 {{ end }}
583 Page functions can be accessed from page and index templates.
585 FEED VARIABLES
587 The following feed variables are available:
588 .Title
590 The title of the feed
591 .Path
593 The path to the feed directory
594 .URL
596 The URL of the feed directory
597 .Pages
599 List of pages in this feed
600 Some of these variables are defined in feed configuration. See FEEDS.
602 Feed variables can be accessed from feed templates.
604 PARTIAL TEMPLATES
606 Partial templates can be placed in the templates/_partials directory.
607 Partial templates can be executed from any other template with the par‐
608 tial function. See TEMPLATE FUNCTIONS.
609 TEMPLATE FUNCTIONS
611 All templates have the following functions available to them:
612 and args...
614 Returns the boolean AND of its arguments by returning the first
615 empty argument or the last argument, that is, "and x y" behaves as
616 "if x then y else x". All the arguments are evaluated.
617 call function, args...
619 Returns the result of calling the first argument, which must be a
620 function, with the remaining arguments as parameters. Thus "call
621 .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where Y is a func-val‐
622 ued field, map entry, or the like. The first argument must be the
623 result of an evaluation that yields a value of function type (as
624 distinct from a predefined function such as print). The function
625 must return either one or two result values, the second of which is
626 of type error. If the arguments don't match the function or the re‐
627 turned error value is non-nil, execution stops.
628 eq arg1, arg2
630 Returns the boolean truth of arg1 == arg2.
631 exec command, input
633 Executes the given external command with input provided as standard
634 input. Returns its standard output.
635 ge arg1, arg2
637 Returns the boolean truth of arg1 >= arg2.
638 gt arg1, arg2
640 Returns the boolean truth of arg1 > arg2.
641 html args...
643 Returns the escaped HTML equivalent of the textual representation
644 of its arguments. This function is unavailable in HTML templates,
645 with a few exceptions.
646 index collection, args...
648 Returns the result of indexing its first argument by the following
649 arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
650 indexed item must be a map, slice, or array.
651 js args...
653 Returns the escaped JavaScript equivalent of the textual represen‐
654 tation of its arguments.
655 le arg1, arg2
657 Returns the boolean truth of arg1 <= arg2.
658 len list
660 Returns the integer length of its argument.
661 lt arg1, arg2
663 Returns the boolean truth of arg1 < arg2.
664 math.Add arg1, arg2
666 Returns arg1 + arg2 as an integer if both arguments are integers,
667 otherwise as a float.
668 math.Sub arg1, arg2
670 Returns arg1 - arg2 as an integer if both arguments are integers,
671 otherwise as a float.
672 math.Mul arg1, arg2
674 Returns arg1 * arg2 as an integer if both arguments are integers,
675 otherwise as a float.
676 math.Div arg1, arg2
678 Returns arg1 / arg2 as a float.
679 math.Mod arg1, arg2
681 Returns arg1 % arg2 as an integer.
682 math.Ceil arg
684 Returns the least integer value greater than or equal to arg.
685 math.Floor arg
687 Returns the greatest integer value less than or equal to arg.
688 math.Log arg
690 Returns the natural logarithm of arg as a float.
691 math.Max arg1, arg2
693 Returns the greater of arg1 and arg2 as an integer if both argu‐
694 ments are integers, otherwise as a float.
695 math.Min arg1, arg2
697 Returns the lesser of arg1 and arg2 as an integer if both arguments
698 are integers, otherwise as a float.
699 math.Pow arg1, arg2
701 Returns arg1 ^ arg2 as a float.
702 math.Round arg
704 Returns the nearest integer to arg, rounding half away from zero.
705 math.Sqrt arg
707 Returns square root of arg as a float.
708 ne arg1, arg2
710 Returns the boolean truth of arg1 != arg2.
711 not arg
713 Returns the boolean negation of its single argument.
714 or args...
716 Returns the boolean OR of its arguments by returning the first non-
717 empty argument or the last argument, that is, "or x y" behaves as
718 "if x then x else y". All the arguments are evaluated.
719 partial name, data
721 Executes the named partial template with the provided data. See
722 PARTIAL TEMPLATES.
723 Example:
725 {{ partial "header.gmi" . }}
727 path.Base path
729 Returns the last element of path.
730 path.Clean path
732 Returns the shortest path name equivalent to path.
733 path.Dir path
735 Returns all but the last element of path, typically the path's di‐
736 rectory.
737 path.Ext path
739 Returns the filename extension used by path.
740 path.Join elem...
742 Joins any number of path elements into a single path.
743 print args...
745 Formats using the default formats for its operands and returns the
746 resulting string. Spaces are added between operands when neither is
747 a string.
748 printf format, args...
750 Formats according to a format specifier and returns the resulting
751 string.
752 println args...
754 Formats using the default formats for its operands and returns the
755 resulting string. Spaces are always added between operands and a
756 newline is appended.
757 reverse list
759 Returns a reversed copy of the provided slice or array.
760 safeCSS css
762 Encapsulates known safe CSS content.
763 safeHTML html
765 Encapsulates a known safe HTML document fragment.
766 safeHTMLAttr attr
768 Encapsulates an HTML attribute from a trusted source.
769 safeJS js
771 Encapsulates a known safe JavaScript expression.
772 safeURL url
774 Encapsulates a known safe URL or URL substring.
775 site
777 Returns site information (see SITE VARIABLES).
778 slice list, args...
780 slice returns the result of slicing its first argument by the re‐
781 maining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2],
782 while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3"
783 is x[1:2:3]. The first argument must be a string, slice, or array.
784 strings.Count string, substr
786 Counts the number of non-overlapping instances of substr in string.
787 If substr is an empty string, Count returns 1 + the number of Uni‐
788 code code points in string.
789 strings.HasPrefix string, prefix
791 Reports whether string begins with prefix.
792 strings.HasSuffix string, suffix
794 Reports whether string ends with suffix.
795 strings.Join elems, sep
797 Concatenates the elements of its first argument to create a single
798 string. The separator string sep is placed between elements in the
799 resulting string.
800 strings.Repeat string, count
802 Returns a new string consisting of count copies of string.
803 It panics if count is negative or if the result of (len(string) *
805 count) overflows.
806 strings.Replace string, old, new, n
808 Returns a copy of string with the first n non-overlapping instances
809 of old replaced by new. If old is empty, it matches at the begin‐
810 ning of the string and after each UTF-8 sequence, yielding up to
811 k+1 replacements for a k-rune string. If n < 0, there is no limit
812 on the number of replacements.
813 strings.ReplaceAll string, old, new
815 Returns a copy of string with all non-overlapping instances of old
816 replaced by new. If old is empty, it matches at the beginning of
817 the string and after each UTF-8 sequence, yielding up to k+1 re‐
818 placements for a k-rune string.
819 strings.Split string, sep
821 Slices string into all substrings separated by sep and returns a
822 slice of the substrings between those separators.
823 If string does not contain sep and sep is not empty, Split returns
825 a slice of length 1 whose only element is string.
826 If sep is empty, Split splits after each UTF-8 sequence. If both
828 string and sep are empty, Split returns an empty slice.
829 strings.Title string
831 Returns a copy of the string with all Unicode letters that begin
832 words mapped to their Unicode title case.
833 BUG: The rule Title uses for word boundaries does not handle Uni‐
835 code punctuation properly.
836 strings.ToLower string
838 Returns string with all Unicode letters mapped to their lower case.
839 strings.ToUpper string
841 Returns string with all Unicode letters mapped to their upper case.
842 strings.Trim string, cutset
844 Returns a slice of string with all leading and trailing Unicode
845 code points contained in cutset removed.
846 strings.TrimLeft string, cutset
848 Returns a slice of string with all leading Unicode code points con‐
849 tained in cutset removed.
850 To remove a prefix, use strings.TrimPrefix instead.
852 strings.TrimPrefix string, prefix
854 Returns string without the provided leading prefix string. If
855 string doesn't start with prefix, it is returned unchanged.
856 strings.TrimRight string, cutset
858 Returns a slice of string with all trailing Unicode code points
859 contained in cutset removed.
860 To remove a suffix, use strings.TrimSuffix instead.
862 strings.TrimSpace string
864 Returns a slice of string with all leading and trailing white space
865 removed, as defined by Unicode.
866 strings.TrimSuffix string, suffix
868 Returns string without the provided trailing suffix string. If
869 string doesn't end with suffix, it is returned unchanged.
870 urlquery args...
872 Returns the escaped value of the textual representation of its ar‐
873 guments in a form suitable for embedding in a URL query. This func‐
874 tion is unavailable in HTML templates, with a few exceptions.
875 2022-10-23 kiln(1)