diff --git a/doc/kiln.1.scd b/doc/kiln.1.scd index 975501a..ccddf19 100644 --- a/doc/kiln.1.scd +++ b/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. -Keys denote the path to the feed input directory and values denote the title of -the feed. +Feeds can be specified in the [feeds] table of the configuration file. Keys +denote the path to the feed input directory and values denote the title of the +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