~adnano/kiln

ref: f87fa392d50d2846119c28e16bc6d29c6a10f7a9 kiln/docs/kiln.1.scd -rw-r--r-- 17.4 KiB
f87fa392Adnan Maolood site: Implement support for task URLs 3 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
kiln(1)

# NAME

kiln - a simple static site generator

# SYNOPSIS

*kiln* build [-c _config_]

*kiln* new _path_

*kiln* version

# DESCRIPTION

*kiln build* builds a kiln site.

*kiln new* creates a new kiln site at the given path.

*kiln version* prints version information for the kiln program.

# OPTIONS

## kiln build

*-c* _config_
	Specifies the configuration file to use. Defaults to "config.toml".

# OVERVIEW

A kiln site is built in one or more steps called *tasks*. Tasks read content
from the content directory, process the content, and write the content to the
output directory. Tasks can also be configured to copy static content to the
output directory.

The following directories are common to all tasks:

[[ *Directory*
:[ *Description*
|  content/
:  Content directory
|  templates/
:  Templates directory

# CONTENT DIRECTORY

The content directory contains site content files, called *pages*, optionally
nested in subdirectories. Any file or directory in the content directory whose
name begins with "\_" will be ignored, with the exception of pages with the name
"\_index" (e.g. "\_index.gmi").

Pages may be preprocessed, run through templates, and postprocessed (in that
order). Each operation takes the output of the last operation as input.

Pages can specify dates in their filenames. For example, the page
content/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date
of November 20, 2020.

Pages with the name "\_index" are index pages and are treated specially.

## FRONTMATTER

Pages can specify additional metadata in frontmatter. Frontmatter is delimited
by "---" and is specified in YAML. Newlines after the closing delimiter are
removed from the content.

Example:

	```
	---
	title: Page title
	date: 2021-04-24
	params:
		custom: value
	---

	Page content
	```

The following keys are supported:

*title*
	The title of the page.

	Example:

	```
	---
	title: My first post
	---
	```

*date*
	The date of the page. Pages are sorted by date in reverse order, so newer
	pages will be placed above older pages.

	Example:

	```
	---
	date: 2021-05-21
	---
	```

*weight*
	The weight of the page. Pages are sorted by weight in increasing order, so
	pages with a smaller weight will be placed above pages with a larger weight.

	Example:

	```
	---
	weight: 1
	---
	```

*params*
	Specifies extra parameters to be provided to templates.

	Example:

	```
	---
	params:
	  key: value
	---
	```

## SORTING

Pages are sorted automatically. Pages are first ordered by weight in increasing
order, then by date from newest to oldest, and then by filename in alphabetical
order.

# TEMPLATES DIRECTORY

The templates directory contains templates for use when building the site.
Templates use the Go templating language. The following templates are supported:

[[ *Template*
:[ *Description*
|  page.ext
:  Page template
|  index.ext
:  Directory index template
|  base.ext
:  Base template from which the page and index templates inherit
|  atom.xml
:  Atom feed template

The extension of page and index templates is configurable and will replace
".ext" above. See *CONFIGURATION*.

The scope of a template is limited by the directory it is placed in. For
example, a template in the templates/blog directory will only apply to files in
content/blog.

Fallback templates can be specified in the templates/\_default directory. These
templates will apply to any directory which does not have its own templates
specified in the template directory.

For more information on the Go templating language, see
https://golang.org/pkg/text/template/.

# CONFIGURATION

By default, kiln looks for a configuration file named "config.toml". An
alternative configuration file can be specified with the *-c* flag. See
*OPTIONS*.

The configuration file uses the _TOML_ format.

The following keys are supported:

[[ *Key*
:[ *Description*
|  title
:  Site title
|  params
:  Extra parameters made available to templates

## PERMALINKS

Permalinks can be used to rewrite page paths. Permalinks are specified in the
\[permalinks] table of the configuration file. Keys denote a path to a directory,
and values use the Go templating language to rewrite the final path of pages in
that directory. The templates have the same data that page templates have
available to them (see *PAGE TEMPLATES*).

The following configuration will rewrite the paths of pages in the content/blog
directory to /YYYY/MM/DD/slug. For example, the file
content/blog/2021-05-12-hello-world.gmi will have a path of
/2021/05/12/hello-world/.

	```
	[permalinks]
	"/blog/" = "/{{ .Date.Format `2006/01/02` }}/{{ path.Base .Path }}"
	```

For more information on templates, see *TEMPLATES*.

## TASKS

Tasks can be specified in the [[tasks]] array of tables.

The following configuration options are supported per task:

*input*
	A list of input file extensions. Files in the content directory with a
	matching extension will be processed.

	Example:

	```
	[[tasks]]
	input = [".gmi", ".md"]
	```

*output*
	The output file extension. Files written to the output directory will use
	this extension.

	Example:

	```
	[[tasks]]
	output = ".html"
	```

*template*
	The template file extension. Templates with this file extension will be used
	to format the content. If unset, no templates will be used.

	Example:

	```
	[[tasks]]
	template = ".gmi"
	```

*preprocess*
	Maps file extensions to preprocess commands. Preprocess commands will run
	before templating. The commands will be provided the content of the page as
	standard input and should write the processed content to standard output.

	Example:

	```
	[[tasks]]
	input = [".gmi", ".md"]
	output = ".html"
	preprocess.gmi = "gmnitohtml"
	preprocess.md = "mdtohtml"
	```

*postprocess*
	Specifies a command which will run after templating and before content is
	written to the output directory. It will be provided the content of the page
	as standard input and should write the processed content to standard output.

	Example:

	```
	[[tasks]]
	input = [".gmi"]
	output = ".html"
	template = ".gmi"
	postprocess = "gmnitohtml"
	```

*static_dir*
	Specifies a directory from which to read static content. All files in this
	directory will be copied to the output directory without modificiation.
	Static assets like images should be stored in this directory. If unset, no
	static content directory will be used.

	Example:

	```
	[[tasks]]
	static_dir = "static"
	```

*output_dir*
	Specifies the directory to which output files will be written.

	Example:

	```
	[[tasks]]
	output_dir = "public"
	```

*url*
	The base URL to use for page URLs. The base URL should not have trailing
	forward slashes.

*ugly_urls*
	Specifies whether page paths will contain file extensions. By default,
	clean paths without any extension are used.

	Example:

	```
	[[tasks]]
	ugly_urls = true
	```

The following configuration builds a simple Gemini site.

	```
	[[tasks]]
	input = [".gmi"]
	output = ".gmi"
	template = ".gmi"
	output_dir = "public"
	```

The following configuration generates a Gemini text site and also exports an
HTML version of the site. This configuration makes use of the *gmnitohtml*(1)
command to convert Gemini text to HTML.

	```
	# Build the site
	[[tasks]]
	input = [".gmi"]
	output = ".gmi"
	template = ".gmi"
	static_dir = "static"
	output_dir = "public"

	# Export an HTML version of the site
	[[tasks]]
	input = [".gmi"]
	output = ".html"
	template = ".gmi"
	postprocess = "gmnitohtml"
	static_dir = "static"
	output_dir = "public.html"
	```

The following configuration generates an HTML site from Markdown files in the
content directory and HTML templates in the templates directory. This
configuration makes use of the *markdown*(1) comand to convert Markdown to HTML.

	```
	[[tasks]]
	input_ext = [".md"]
	output_ext = ".html"
	template_ext = ".html"
	preprocess.md = "markdown"
	static_dir = "static"
	output_dir = "public"
	```

## FEEDS

Feeds can be specified in the [[tasks.feeds]] array of tables. Multiple feeds
can be specified per task.

Example feed configuration:

	```
	[[tasks]]
	# ...

	# This generates a feed for the files in content/blog
	# and writes it to blog/atom.xml (relative to the output directory)
	[[tasks.feeds]]
	input_dir = "blog"
	title = "My Blog"
	template = "atom.xml"
	output = "blog/atom.xml"

	# You can generate multiple feeds per task
	# The generated feed can be written anywhere
	# Here it is written to feed.xml (relative to the output directory)
	[[tasks.feeds]]
	input_dir = "blog"
	title = "My Blog"
	template = "custom_feed.xml"
	output = "feed.xml"
	```

*input_dir*
	the content folder with which to populate the feed

*title*
	the title of the feed, accessible via {{ .Title }} in the feed template

*template*
	the template to use for the feed

*output*
	the output path for the rendered feed

# TEMPLATES

Templates have certain data and functions available to them.

## TEMPLATE FUNCTIONS

All templates have the following functions available to them:

*and* _args..._
	Returns the boolean AND of its arguments by returning the
	first empty argument or the last argument, that is,
	"and x y" behaves as "if x then y else x". All the
	arguments are evaluated.

*call* _function_, _args..._
	Returns the result of calling the first argument, which
	must be a function, with the remaining arguments as parameters.
	Thus "call .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where
	Y is a func-valued field, map entry, or the like.
	The first argument must be the result of an evaluation
	that yields a value of function type (as distinct from
	a predefined function such as print). The function must
	return either one or two result values, the second of which
	is of type error. If the arguments don't match the function
	or the returned error value is non-nil, execution stops.

*eq* _arg1_, _arg2_
	Returns the boolean truth of _arg1_ == _arg2_.

*exec* _command_, _input_
	Executes the given external command with _input_ provided as standard input.
	Returns its standard output.

*ge* _arg1_, _arg2_
	Returns the boolean truth of _arg1_ >= _arg2_.

*gt* _arg1_, _arg2_
	Returns the boolean truth of _arg1_ > _arg2_.

*html* _args..._
	Returns the escaped HTML equivalent of the textual
	representation of its arguments. This function is unavailable
	in HTML templates, with a few exceptions.

*index* _collection_, _args..._
	Returns the result of indexing its first argument by the
	following arguments. Thus "index x 1 2 3" is, in Go syntax,
	x[1][2][3]. Each indexed item must be a map, slice, or array.

*js* _args..._
	Returns the escaped JavaScript equivalent of the textual
	representation of its arguments.

*le* _arg1_, _arg2_
	Returns the boolean truth of _arg1_ <= _arg2_.

*len* _list_
	Returns the integer length of its argument.

*lt* _arg1_, _arg2_
	Returns the boolean truth of _arg1_ < _arg2_.

*ne* _arg1_, _arg2_
	Returns the boolean truth of _arg1_ != _arg2_.

*not* _arg_
	Returns the boolean negation of its single argument.

*or* _args..._
	Returns the boolean OR of its arguments by returning the
	first non-empty argument or the last argument, that is,
	"or x y" behaves as "if x then x else y". All the
	arguments are evaluated.

*partial* _name_, _data_
	Executes the named partial template with the provided data. See *PARTIAL
	TEMPLATES*.

	Example:

	```
	{{ partial "header.gmi" . }}
	```

*path.Base* _path_
	Returns the last element of _path_.

*path.Clean* _path_
	Returns the shortest path name equivalent to _path_.

*path.Dir* _path_
	Returns all but the last element of _path_, typically the path's directory.

*path.Ext* _path_
	Returns the filename extension used by _path_.

*path.Join* _elem..._
	Joins any number of path elements into a single path.

*print* _args..._
	Formats using the default formats for its operands and returns the resulting
	string. Spaces are added between operands when neither is a string.

*printf* _format_, _args..._
	Formats according to a format specifier and returns the resulting string.

*println* _args..._
	Formats using the default formats for its operands and returns the resulting
	string. Spaces are always added between operands and a newline is appended.

*reverse* _list_
	Returns a reversed copy of the provided slice or array.

*safeCSS* _css_
	Encapsulates known safe CSS content.

*safeHTML* _html_
	Encapsulates a known safe HTML document fragment.

*safeHTMLAttr* _attr_
	Encapsulates an HTML attribute from a trusted source.

*safeJS* _js_
	Encapsulates a known safe JavaScript expression.

*safeURL* _url_
	Encapsulates a known safe URL or URL substring.

*site*
	Returns site metadata (see *SITE METADATA*).

*slice* _list_, _args..._
	slice returns the result of slicing its first argument by the
	remaining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2],
	while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3"
	is x[1:2:3]. The first argument must be a string, slice, or array.

*strings.Count* _string_, _substr_
	Counts the number of non-overlapping instances of _substr_ in _string_.
	If _substr_ is an empty string, Count returns 1 + the number of Unicode code
	points in _string_.

*strings.HasPrefix* _string_, _prefix_
	Reports whether _string_ begins with _prefix_.

*strings.HasSuffix* _string_, _suffix_
	Reports whether _string_ ends with _suffix_.

*strings.Join* _elems_, _sep_
	Concatenates the elements of its first argument to create a single string.
	The separator string _sep_ is placed between elements in the resulting
	string.

*strings.Repeat* _string_, _count_
	Returns a new string consisting of _count_ copies of _string_.

	It panics if _count_ is negative or if the result of
	(len(_string_) \* _count_) overflows.

*strings.Replace* _string_, _old_, _new_, _n_
	Returns a copy of _string_ with the first _n_ non-overlapping instances of
	_old_ replaced by _new_. If _old_ is empty, it matches at the beginning of
	the string and after each UTF-8 sequence, yielding up to k+1 replacements
	for a k-rune string. If _n_ < 0, there is no limit on the number of
	replacements.

*strings.ReplaceAll* _string_, _old_, _new_
	Returns a copy of _string_ with all non-overlapping instances of _old_
	replaced by _new_. If _old_ is empty, it matches at the beginning of the
	string and after each UTF-8 sequence, yielding up to k+1 replacements for a
	k-rune string.

*strings.Split* _string_, _sep_
	Slices _string_ into all substrings separated by _sep_ and returns a slice
	of the substrings between those separators.

	If _string_ does not contain _sep_ and _sep_ is not empty, Split returns a
	slice of length 1 whose only element is _string_.

	If _sep_ is empty, Split splits after each UTF-8 sequence. If both _string_
	and _sep_ are empty, Split returns an empty slice.

*strings.Title* _string_
	Returns a copy of the string with all Unicode letters that begin words
	mapped to their Unicode title case.

	*BUG:* The rule Title uses for word boundaries does not handle Unicode
	punctuation properly.

*strings.ToLower* _string_
	Returns _string_ with all Unicode letters mapped to their lower case.

*strings.ToUpper* _string_
	Returns _string_ with all Unicode letters mapped to their upper case.

*strings.Trim* _string_, _cutset_
	Returns a slice of _string_ with all leading and trailing Unicode code
	points contained in _cutset_ removed.

*strings.TrimLeft* _string_, _cutset_
	Returns a slice of _string_ with all leading Unicode code points contained
	in _cutset_ removed.

	To remove a prefix, use *strings.TrimPrefix* instead.

*strings.TrimPrefix* _string_, _prefix_
	Returns _string_ without the provided leading _prefix_ string. If _string_
	doesn't start with _prefix_, it is returned unchanged.

*strings.TrimRight* _string_, _cutset_
	Returns a slice of _string_ with all trailing Unicode code points contained
	in _cutset_ removed.

	To remove a suffix, use *strings.TrimSuffix* instead.

*strings.TrimSpace* _string_
	Returns a slice of _string_ with all leading and trailing white space
	removed, as defined by Unicode.

*strings.TrimSuffix* _string_, _suffix_
	Returns _string_ without the provided trailing _suffix_ string. If _string_
	doesn't end with _suffix_, it is returned unchanged.

*urlquery* _args..._
	Returns the escaped value of the textual representation of
	its arguments in a form suitable for embedding in a URL query.
	This function is unavailable in HTML templates, with a few
	exceptions.

## SITE METADATA

Site metadata contains the following data:

*Title*
	The title of the site.

*Params*
	Extra parameters specified in configuration.

*Generated*
	Site generation time.

To configure these variables, see *CONFIGURATION*.

## PAGE TEMPLATES

Page templates are provided with the following data:

*Title*
	The title of the page

*Date*
	The date of the page

*Weight*
	The weight of the page

*Path*
	The path to the page

*URL*
	The URL of the page. If no base URL is configured, it is equivalent to
	*Path*.

*FilePath*
	The path of the page file relative to the content directory

*Content*
	The contents of the page

*Params*
	Extra parameters specified in frontmatter

*Prev*
	The previous page in this directory

*Next*
	The next page in this directory

## INDEX TEMPLATES

Index templates are provided with all the data that page templates are provided,
plus the following data:

*Pages*
	List of pages in this directory

*Dirs*
	List of subdirectories

## FEED TEMPLATES

Feed templates are provided with the following data:

*Title*
	Title of the feed

*Path*
	The path to the feed directory

*URL*
	The URL of the feed directory

*Pages*
	List of pages in this feed

## PARTIAL TEMPLATES

Partial templates can be specified in the templates/\_partials directory.
Partial templates can be executed from any other template with the *partial*
function. See *TEMPLATE FUNCTIONS*.