docs: Update documentation

docs/kiln.1.scd

@@ -29,10 +29,10 @@ kiln - a simple static site generator
 
 # OVERVIEW
 
-A kiln site is built in one or more steps called *tasks*.
+A kiln site is built in one or more steps called *tasks*. Tasks read content
-Tasks read content from the content directory, process the content, and write
+from the content directory, process the content, and write the content to the
-the content to the output directory. Tasks can also be configured to copy static
+output directory. Tasks can also be configured to copy static content to the
-content to the output directory.
+output directory.
 
 The following directories are common to all tasks:
 
@@ -47,23 +47,23 @@ The following directories are common to all tasks:
 
 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.
+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.
 
-; TODO: Should we remove this behavior and opt for using frontmatter instead?
 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.
+Pages with the name "\_index" are index pages and are treated specially.
 
 ## FRONTMATTER
 
-Content files can specify additional metadata in frontmatter. Frontmatter is
+Pages can specify additional metadata in frontmatter. Frontmatter is delimited
-delimited by "---" and is specified in YAML. Newlines after the closing
+by "---" and is specified in YAML. Newlines after the closing delimiter are
-delimiter are removed from the content.
+removed from the content.
 
 Example:
 
@@ -100,6 +100,8 @@ Templates use the Go templating language. The following templates are supported:
 :  Page template
 |  index.ext
 :  Directory index template
+|  base.ext
+:  Base template from which the page and index templates inherit
 |  atom.xml
 :  Atom feed template
 
@@ -111,8 +113,8 @@ 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 files which do not have their own templates
+templates will apply to any directory which does not have its own templates
-specified.
+specified in the template directory.
 
 For more information on the Go templating language, see
 https://golang.org/pkg/text/template/.
@@ -123,7 +125,7 @@ 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_ configuration file format.
+The configuration file uses the _TOML_ format.
 
 The following keys are supported:
 
@@ -175,51 +177,116 @@ For more information on templates, see *TEMPLATES*.
 
 ## TASKS
 
-Tasks can be specified in the [tasks] table. Each task must have a unique name.
+Tasks can be specified in the [[tasks]] array of tables.
 
-The following keys are supported per task:
+The following configuration options are supported per task:
 
-[[ *Key*
+*input*
-:[ *Description*
+	A list of input file extensions. Files in the content directory with a
-|  input
+	matching extension will be processed.
-:  Input file extensions
-|  output
-:  Output file extension
-|  template
-:  Template file extension
-|  preprocess
-:  Preprocess commands
-|  postprocess
-:  Postprocess command
-|  static_dir
-:  Static content directory
-|  output_dir
-:  Output directory
 
-The input file extension specifies which files from the content directory to
+	Example:
-process. Only files which have the same extension will be processed.
 
-The output file extension specifies the extension of the file that is written to
+	```
-the output directory.
+	[[tasks]]
+	input = [".gmi", ".md"]
+	```
 
-The template file extension specifies the extension of the templates that will
+*output*
-be used in the templates directory. If unset, no templates will be used.
+	The output file extension. Files written to the output directory will use
+	this extension.
 
-The preprocess commands specify commands which will run before content is
+	Example:
-passed to a template. It will be provided the content as standard input and
-should write the processed content to standard output.
 
-The postprocess command specifies a command which will run after templating
+	```
-and before content is written to the output directory. It will be provided the
+	[[tasks]]
-content as standard input and should write the content to standard output.
+	output = ".html"
+	```
 
-The static content directory controls which directory to use for static content.
+*template*
-If unset, no static content directory will be used. All files in this directory
+	The template file extension. Templates with this file extension will be used
-will be copied to the output directory without modification. Static assets like
+	to format the content. If unset, no templates will be used.
-images should be stored in this directory.
 
-The output directory specifies the directory to which the output files will be
+	Example:
-written.
+
+	```
+	[[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"
+	```
+
+*ugly_urls*
+	Specifies whether page permalinks will contain file extensions. By default,
+	clean URLs 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)
@@ -328,6 +395,16 @@ All templates have the following functions available to them:
 	"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_.
 
@@ -477,6 +554,16 @@ All templates have the following functions available to them:
 
 Site metadata contains the following data:
 
+package main
+
+import (
+	"fmt"
+	"path"
+)
+
+func main() {
+	fmt.Println(path.Join("https://example.com", "hello-world"))
+}
 [[ *Variable*
 :[ *Description*
 |  Title
@@ -528,3 +615,8 @@ Feed templates are provided with the following data:
 |  Entries
 :  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*.