1kiln(1)                     General Commands Manual                    kiln(1)
2
3
4

NAME

6       kiln - a simple static site generator
7

SYNOPSIS

9       kiln build [-c config]
10
11       kiln new path
12

DESCRIPTION

14       kiln build builds a kiln site.
15
16       kiln new creates a new kiln site at the given path.
17

OPTIONS

19   kiln build
20       -c config
21           Specifies the configuration file to use. Defaults to "config.toml".
22

OVERVIEW

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
29       The following directories are common to all tasks:
30
31       ┌───────────┬─────────────────────┐
32Directory  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

CONTENT DIRECTORY

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
49       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
53       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
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                 key: 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       outputs
108           Optionally specifies a list of tasks that can build this page. De‐
109           faults to all tasks.
110
111           Example:
112
113               ---
114               outputs: ["Gemini", "HTTPS"]
115               ---
116
117               ---
118               outputs: [] # Excluded from all tasks
119               ---
120
121       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
127           Example:
128
129               ---
130               title: About me
131               template: about
132               ---
133
134       params
135           Specifies extra parameters to be provided to templates.
136
137           Example:
138
139               ---
140               params:
141                 key: value
142               ---
143
144   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

TEMPLATES DIRECTORY

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
154       ┌──────────┬──────────────────────────┐
155Template  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
170       For more information on the Go templating language, see
171       https://golang.org/pkg/text/template/.
172
173   PAGE AND INDEX TEMPLATES
174       The content for page and index templates can be accessed using the
175       .Content page variable. For example:
176
177           page header
178           {{ .Content }}
179           page footer
180
181       Other page variables are documented in PAGE VARIABLES.
182
183       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
187           <body>
188           {{ .Content | safeHTML }}
189           </body>
190
191       See TEMPLATE FUNCTIONS for more information.
192
193   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
198       For example, the base template could contain:
199
200           {{ block "body" . }}
201                Blocks can have default content
202           {{ end }}
203           {{ block "extra_content" . }}{{ end }}
204
205       The page and index templates can then customize these blocks, for exam‐
206       ple:
207
208           {{ define "body" }}
209                Body goes here
210           {{ end }}
211
212   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
218       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
222       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
225       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
230       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
235       There is no override mechanism for base templates.
236
237   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
242           {{ partial "navbar.ext" . }}
243
244       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
248       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
252           <body>
253           {{ partial "navbar.ext" . | safeHTML }}
254           </body>
255
256       See TEMPLATE FUNCTIONS for more information.
257

CONFIGURATION

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
263       The configuration file uses the TOML format.
264
265       The following keys are supported:
266
267       ┌───────┬────────────────────────┐
268Key    Description            
269       ├───────┼────────────────────────┤
270       │title  │ Site title             │
271       ├───────┼────────────────────────┤
272       │params │ Extra parameters made  │
273       │       │ available to templates │
274       └───────┴────────────────────────┘
275
276   TASKS
277       Tasks can be specified in the [[tasks]] array of tables.
278
279       The following configuration options are supported per task:
280
281       name
282           An optional name for the task.
283
284           Example:
285
286               [[tasks]]
287               name = "Gemini"
288
289               [[tasks]]
290               name = "HTML export"
291
292       input
293           A list of input file extensions. Files in the content directory
294           with a matching extension will be processed.
295
296           Example:
297
298               [[tasks]]
299               input = [".gmi", ".md"]
300
301       output
302           The output file extension. Files written to the output directory
303           will use this extension.
304
305           Example:
306
307               [[tasks]]
308               output = ".html"
309
310       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
315           Example:
316
317               [[tasks]]
318               template = ".gmi"
319
320       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
326           Example:
327
328               [[tasks]]
329               input = [".gmi", ".md"]
330               output = ".html"
331               preprocess.gmi = "gmnitohtml"
332               preprocess.md = "mdtohtml"
333
334       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
340           Example:
341
342               [[tasks]]
343               input = [".gmi"]
344               output = ".html"
345               template = ".gmi"
346               postprocess = "gmnitohtml"
347
348       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
354           Example:
355
356               [[tasks]]
357               static_dir = "static"
358
359       output_dir
360           Specifies the directory to which output files will be written.
361
362           Example:
363
364               [[tasks]]
365               output_dir = "public"
366
367       url
368           The base URL to use for page URLs. The base URL should not have
369           trailing forward slashes.
370
371       ugly_urls
372           Specifies whether page paths will contain file extensions. By de‐
373           fault, clean paths without any extension are used.
374
375           Example:
376
377               [[tasks]]
378               ugly_urls = true
379
380       The following configuration builds a simple Gemini site.
381
382               [[tasks]]
383               input = [".gmi"]
384               output = ".gmi"
385               template = ".gmi"
386               output_dir = "public"
387
388       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
392               # Build the site
393               [[tasks]]
394               input = [".gmi"]
395               output = ".gmi"
396               template = ".gmi"
397               static_dir = "static"
398               output_dir = "public"
399
400               # 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
409       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
415               [[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
424   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
432       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
437               [[tasks]]
438               # ...
439
440               [tasks.permalinks]
441               "/blog/" = "/{{ .Date.Format `2006/01/02` }}/{{ path.Base .Path }}"
442
443       For more information on templates, see TEMPLATES.
444
445   FEEDS
446       Feeds can be specified in the [[tasks.feeds]] array of tables. Multiple
447       feeds can be specified per task.
448
449       Example feed configuration:
450
451               [[tasks]]
452               # ...
453
454               # 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
462               # 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
471       input_dir
472           the content folder with which to populate the feed
473
474       title
475           the title of the feed, accessible via {{ .Title }} in the feed tem‐
476           plate
477
478       template
479           the template to use for the feed
480
481       output
482           the output path for the rendered feed
483

TEMPLATES

485       Templates have certain data and functions available to them.
486
487   SITE VARIABLES
488       The following site-wide variables are available:
489
490       .Title
491           The title of the site.
492
493       .Params
494           Extra parameters specified in configuration.
495
496       .Generated
497           Site generation time.
498
499       .Root
500           The root page of the site. See PAGE VARIABLES.
501
502       Some of these variables are defined in your site's configuration. See
503       CONFIGURATION.
504
505       Site variables can be accessed from templates with the site function.
506       See TEMPLATE FUNCTIONS.
507
508   PAGE VARIABLES
509       The following page variables are available:
510
511       .Title
512           The title of the page
513
514       .Date
515           The date of the page
516
517       .Weight
518           The weight of the page
519
520       .Path
521           The path to the page
522
523       .URL
524           The URL of the page. If no base URL is configured, it is equivalent
525           to .Path.
526
527       .FilePath
528           The path of the page file or directory relative to the content di‐
529           rectory
530
531       .Content
532           The contents of the page
533
534       .Params
535           Extra parameters specified in frontmatter
536
537       .Prev
538           The previous page in sorted order
539
540       .Next
541           The next page in sorted order
542
543       .Pages
544           List of pages in this directory
545
546       .Dirs
547           List of subdirectories in this directory
548
549       Some of these variables are defined in page frontmatter. See FRONTMAT‐
550       TER.
551
552       Page variables can be accessed from page and index templates.
553
554   PAGE FUNCTIONS
555       The following page functions are available:
556
557       .GetPage path
558           Retrieves the page in this directory with the given path, which may
559           be relative or absolute.
560
561           Example:
562
563               {{/* 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
571               {{/* 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
579               {{/* Retrieve a page relative to the current directory */}}
580               {{ with .GetPage "posts/hello-world.gmi" }}
581                    {{ .Title }}
582               {{ end }}
583
584       Page functions can be accessed from page and index templates.
585
586   FEED VARIABLES
587       The following feed variables are available:
588
589       .Title
590           The title of the feed
591
592       .Path
593           The path to the feed directory
594
595       .URL
596           The URL of the feed directory
597
598       .Pages
599           List of pages in this feed
600
601       Some of these variables are defined in feed configuration. See FEEDS.
602
603       Feed variables can be accessed from feed templates.
604
605   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
610   TEMPLATE FUNCTIONS
611       All templates have the following functions available to them:
612
613       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
618       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
629       eq arg1, arg2
630           Returns the boolean truth of arg1 == arg2.
631
632       exec command, input
633           Executes the given external command with input provided as standard
634           input. Returns its standard output.
635
636       ge arg1, arg2
637           Returns the boolean truth of arg1 >= arg2.
638
639       gt arg1, arg2
640           Returns the boolean truth of arg1 > arg2.
641
642       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
647       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
652       js args...
653           Returns the escaped JavaScript equivalent of the textual represen‐
654           tation of its arguments.
655
656       le arg1, arg2
657           Returns the boolean truth of arg1 <= arg2.
658
659       len list
660           Returns the integer length of its argument.
661
662       lt arg1, arg2
663           Returns the boolean truth of arg1 < arg2.
664
665       math.Add arg1, arg2
666           Returns arg1 + arg2 as an integer if both arguments are integers,
667           otherwise as a float.
668
669       math.Sub arg1, arg2
670           Returns arg1 - arg2 as an integer if both arguments are integers,
671           otherwise as a float.
672
673       math.Mul arg1, arg2
674           Returns arg1 * arg2 as an integer if both arguments are integers,
675           otherwise as a float.
676
677       math.Div arg1, arg2
678           Returns arg1 / arg2 as a float.
679
680       math.Mod arg1, arg2
681           Returns arg1 % arg2 as an integer.
682
683       math.Ceil arg
684           Returns the least integer value greater than or equal to arg.
685
686       math.Floor arg
687           Returns the greatest integer value less than or equal to arg.
688
689       math.Log arg
690           Returns the natural logarithm of arg as a float.
691
692       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
696       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
700       math.Pow arg1, arg2
701           Returns arg1 ^ arg2 as a float.
702
703       math.Round arg
704           Returns the nearest integer to arg, rounding half away from zero.
705
706       math.Sqrt arg
707           Returns square root of arg as a float.
708
709       ne arg1, arg2
710           Returns the boolean truth of arg1 != arg2.
711
712       not arg
713           Returns the boolean negation of its single argument.
714
715       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
720       partial name, data
721           Executes the named partial template with the provided data. See
722           PARTIAL TEMPLATES.
723
724           Example:
725
726               {{ partial "header.gmi" . }}
727
728       path.Base path
729           Returns the last element of path.
730
731       path.Clean path
732           Returns the shortest path name equivalent to path.
733
734       path.Dir path
735           Returns all but the last element of path, typically the path's di‐
736           rectory.
737
738       path.Ext path
739           Returns the filename extension used by path.
740
741       path.Join elem...
742           Joins any number of path elements into a single path.
743
744       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
749       printf format, args...
750           Formats according to a format specifier and returns the resulting
751           string.
752
753       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
758       reverse list
759           Returns a reversed copy of the provided slice or array.
760
761       safeCSS css
762           Encapsulates known safe CSS content.
763
764       safeHTML html
765           Encapsulates a known safe HTML document fragment.
766
767       safeHTMLAttr attr
768           Encapsulates an HTML attribute from a trusted source.
769
770       safeJS js
771           Encapsulates a known safe JavaScript expression.
772
773       safeURL url
774           Encapsulates a known safe URL or URL substring.
775
776       site
777           Returns site information (see SITE VARIABLES).
778
779       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
785       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
790       strings.HasPrefix string, prefix
791           Reports whether string begins with prefix.
792
793       strings.HasSuffix string, suffix
794           Reports whether string ends with suffix.
795
796       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
801       strings.Repeat string, count
802           Returns a new string consisting of count copies of string.
803
804           It panics if count is negative or if the result of (len(string) *
805           count) overflows.
806
807       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
814       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
820       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
824           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
827           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
830       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
834           BUG: The rule Title uses for word boundaries does not handle Uni‐
835           code punctuation properly.
836
837       strings.ToLower string
838           Returns string with all Unicode letters mapped to their lower case.
839
840       strings.ToUpper string
841           Returns string with all Unicode letters mapped to their upper case.
842
843       strings.Trim string, cutset
844           Returns a slice of string with all leading and trailing Unicode
845           code points contained in cutset removed.
846
847       strings.TrimLeft string, cutset
848           Returns a slice of string with all leading Unicode code points con‐
849           tained in cutset removed.
850
851           To remove a prefix, use strings.TrimPrefix instead.
852
853       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
857       strings.TrimRight string, cutset
858           Returns a slice of string with all trailing Unicode code points
859           contained in cutset removed.
860
861           To remove a suffix, use strings.TrimSuffix instead.
862
863       strings.TrimSpace string
864           Returns a slice of string with all leading and trailing white space
865           removed, as defined by Unicode.
866
867       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
871       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
876
877
878                                  2023-07-20                           kiln(1)
Impressum