From a4a8600c1eed059b46e76efc8104b68e58efb170 Mon Sep 17 00:00:00 2001 From: adnano Date: Fri, 21 May 2021 16:41:35 -0400 Subject: [PATCH] docs: Update documentation --- docs/kiln.1.scd | 190 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 141 insertions(+), 49 deletions(-) diff --git a/docs/kiln.1.scd b/docs/kiln.1.scd index 64bae59..db999f5 100644 --- a/docs/kiln.1.scd +++ b/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*. -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. +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: @@ -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 -delimited by "---" and is specified in YAML. Newlines after the closing -delimiter are removed from the content. +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: @@ -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 -specified. +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/. @@ -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* -:[ *Description* -| input -: 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 +*input* + A list of input file extensions. Files in the content directory with a + matching extension will be processed. -The input file extension specifies which files from the content directory to -process. Only files which have the same extension will be processed. + Example: -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 -be used in the templates directory. If unset, no templates will be used. +*output* + 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 -passed to a template. It will be provided the content as standard input and -should write the processed content to standard output. + Example: -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. + ``` + [[tasks]] + output = ".html" + ``` -The static content directory controls which directory to use for static content. -If unset, no static content directory will be used. All files in this directory -will be copied to the output directory without modification. Static assets like -images should be stored in this directory. +*template* + The template file extension. Templates with this file extension will be used + to format the content. If unset, no templates will be used. -The output directory specifies the directory to which the output files will be -written. + 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" + ``` + +*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*.