Document tasks

doc/kiln.1.scd

@@ -55,6 +55,88 @@ The following keys are supported:
 Site URLs may contain paths, but should not end with a trailing slash. Multiple
 site URLs may be specified for sites that are available at multiple locations.
 
+## TASKS
+
+Tasks can be specified in the [tasks] table. Each task must have a unique name.
+
+The following keys are supported per task:
+
+[[ *Key*
+:[ *Description*
+|  input_ext
+:  Input file extension
+|  output_ext
+:  Output file extension
+|  template_ext
+:  Template file extension
+|  preprocess
+:  Preprocess command
+|  postprocess
+:  Postprocess command
+|  static_dir
+:  Static content directory
+|  output_dir
+:  Output directory
+
+The input file extension controls which files from the content directory to
+process. Only files which have the same extension will be processed.
+
+The output file extension controls the extension of the file that is written to
+the output directory.
+
+The template file extension specifies the extension of the templates that will
+be used in the template directory. If unset, no templates will be used.
+
+The static content directory controls which directory to use for static content.
+If unset, no static content directory will be used.
+
+The output directory specifies the directory to write the output files.
+
+The preprocess command specifies a command which will run before the content is
+passed to the template. It will be provided the content of the file 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 the content is written to the output directory. It will be provided
+the content of the file as standard input and should write the processed content
+to standard output.
+
+The following configuration generates a Gemini text site and also exports an
+HTML version of the site. This configuration makes use of the *geminitohtml*(1)
+command to convert Gemini text to HTML.
+
+	```
+	# Build the site
+	[tasks.gemini]
+	input_ext = ".gmi"
+	output_ext = ".gmi"
+	template_ext = ".gmi"
+	static_dir = "static"
+	output_dir = "public"
+
+	# Export an HTML version of the site
+	[tasks.geminitohtml]
+	input_ext = ".html"
+	output_ext = ".gmi"
+	template_ext = ".gmi"
+	postprocess = "geminitohtml"
+	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 template directory. This
+configuration makes use of the *markdown*(1) comand to convert Markdown to HTML.
+
+	```
+	[tasks.markdowntohtml]
+	input_ext = ".md"
+	output_ext = ".html"
+	preprocess = "markdown"
+	static_dir = "static"
+	output_dir = "public"
+	```
+
 ## CONTENT DIRECTORY
 
 The content directory contains content that should be processed before
@@ -166,11 +248,20 @@ found at gemini://gemini.circumlunar.space/docs/companion/subscription.gmi.
 
 ## FEEDS
 
-Feeds can optionally be specified in the *feeds* table of the configuration file.
+Feeds can be specified in the [feeds] table of the configuration file. Keys
-Keys denote the path to the feed input directory and values denote the title of
+denote the path to the feed input directory and values denote the title of the
-the feed.
+feed.
 
-Feeds are written to the directory path plus "atom.xml".
+Feeds are written to the output directory plus the feed directory plus
+"atom.xml".
+
+Example feed configuration:
+
+	```
+	# This will generate a feed which will be written to public/blog/atom.xml
+	[feeds]
+	"/blog/" = "My blog"
+	```
 
 ## FEED TEMPLATES