From 951b8a9d5ea1aacec706563576b988406c7c1655 Mon Sep 17 00:00:00 2001 From: Adnan Maolood Date: Sat, 24 Apr 2021 14:11:22 -0400 Subject: [PATCH] Update documentation --- docs/kiln.1.scd | 88 ++++++++++++++++++++++++++----------------------- 1 file changed, 46 insertions(+), 42 deletions(-) diff --git a/docs/kiln.1.scd b/docs/kiln.1.scd index acaafa2..8d7a66c 100644 --- a/docs/kiln.1.scd +++ b/docs/kiln.1.scd @@ -41,7 +41,7 @@ content to the output directory. The following directories are common to all tasks: -|[ *Directory* +[[ *Directory* :[ *Description* | content/ : Content directory @@ -55,7 +55,7 @@ information on TOML, see https://toml.io/en/v0.4.0. The following keys are supported: -|[ *Key* +[[ *Key* :[ *Description* | title : Site title @@ -71,7 +71,7 @@ Tasks can be specified in the [tasks] table. Each task must have a unique name. The following keys are supported per task: -|[ *Key* +[[ *Key* :[ *Description* | input_ext : Input file extension @@ -88,31 +88,31 @@ The following keys are supported per task: | output_dir : Output directory -The input file extension controls which files from the content directory to +The input file extension specifies 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 file extension specifies 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 preprocess command specifies a command which will run before content is +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 +content as standard input and should write the content to standard output. + 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 output directory specifies the directory to which the output files will be +written. 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) +HTML version of the site. This configuration makes use of the *gmnitohtml*(1) command to convert Gemini text to HTML. ``` @@ -125,11 +125,11 @@ command to convert Gemini text to HTML. output_dir = "public" # Export an HTML version of the site - [tasks.geminitohtml] + [tasks.exporthtml] input_ext = ".html" output_ext = ".gmi" template_ext = ".gmi" - postprocess = "geminitohtml" + postprocess = "gmnitohtml" static_dir = "static" output_dir = "public.html" ``` @@ -142,6 +142,7 @@ configuration makes use of the *markdown*(1) comand to convert Markdown to HTML. [tasks.markdowntohtml] input_ext = ".md" output_ext = ".html" + template_ext = ".html" preprocess = "markdown" static_dir = "static" output_dir = "public" @@ -168,22 +169,25 @@ this directory. The template directory contains templates for use when building the site. Templates use the Go templating language. The following templates are supported: -|[ *Template* +[[ *Template* :[ *Description* -| page.gmi +| page.ext : Page template -| index.gmi +| index.ext : Directory index template | atom.xml : Atom feed template +where ".ext" is replaced with the template file extension specified in the +task's template_ext configuration option. + The scope of a template is limited to the directory it is placed in. For example, the template templates/blog/page.gmi will only apply to pages in content/blog. -kiln has default templates built-in. To override the default templates, put -templates in the templates/\_default directory. These templates will apply to -any directory which does not have its own templates specified. +Fallback templates can be specified in the templates/\_default directory. These +templates will be applied to any directory which does not have its own templates +specified. For more information on the Go templating language, see https://golang.org/pkg/text/template/. @@ -192,7 +196,7 @@ https://golang.org/pkg/text/template/. All templates have the following functions available to them: -|[ *Function* +[[ *Function* :[ *Description* | site : Returns site metadata @@ -201,7 +205,7 @@ All templates have the following functions available to them: Site metadata contains the following data: -|[ *Variable* +[[ *Variable* :[ *Description* | Title : The title of the site. @@ -214,7 +218,7 @@ To configure these variables, see *CONFIGURATION*. Page templates are provided with the following data: -|[ *Variable* +[[ *Variable* :[ *Description* | Title : The title of the page @@ -229,15 +233,21 @@ Pages can specify dates in their filenames. For example, the file content/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date of November 20, 2020. -Pages can specify a title in a top-level heading line. The heading must be the -first line in the page, and can optionally be followed by a blank line. Both -lines will be removed from the page content. +Pages can also specify dates and titles in frontmatter. For example: + + ``` + --- + title: Page title + date: 2021-04-24 + --- + Page content + ``` ## INDEX TEMPLATES Index templates are provided with the following data: -|[ *Variable* +[[ *Variable* :[ *Description* | Title : Title of the directory @@ -250,17 +260,13 @@ Index templates are provided with the following data: | Dirs : List of subdirectories -The title and content are taken from the index.gmi file in the directory. If no -index.gmi file exists, then the index template will not be rendered. - -The default index template implements the lightweight subscription specification -found at gemini://gemini.circumlunar.space/docs/companion/subscription.gmi. +The title and content are taken from the index file in the directory. If no +index file exists, then the index template will not be rendered. ## FEEDS 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. +denote the path to the feed directory and values denote the title of the feed. Feeds are written to the output directory plus the feed directory plus "atom.xml". @@ -275,9 +281,9 @@ Example feed configuration: ## FEED TEMPLATES -Feed templates are provided with the following data: +Atom feed templates are provided with the following data: -|[ *Variable* +[[ *Variable* :[ *Description* | Title : Title of the feed @@ -286,5 +292,3 @@ Feed templates are provided with the following data: | Entries : List of pages in this feed -The default feed template uses the site URLs, if any, to turn relative links -into absolute URLs.