diff --git a/doc/kiln.1.scd b/doc/kiln.1.scd index 5f689ac..092e6da 100644 --- a/doc/kiln.1.scd +++ b/doc/kiln.1.scd @@ -2,39 +2,80 @@ kiln(1) # NAME -kiln - a simple static site generator for Gemini sites +kiln - a simple static site generator # SYNOPSIS -_kiln_ [--html] +_kiln_ [-c ] [-t ] # OPTIONS -\--format - Specifies the output format to use. Supported formats include gemini and html. Defaults to "gemini". +\-c + Specifies the configuration file to use. Defaults to "config.toml". -# SITE STRUCTURE +\-t + Specifies the task to run. Defaults to "all", which runs all tasks. -A kiln site is structured in the following way: +# OVERVIEW + +A kiln site is built in one or more steps called _tasks_. + +There is only one default task called "gemini" which builds a Gemini site. + +The following directories are used by default: [[ *Directory* :[ *Description* | content/ -: Site source +: Content directory +| static/ +: Static content directory | templates/ -: Site templates +: Template directory | public/ -: Site destination +: Output directory -All files in the source directory will be copied to the destination directory. -If the file is a Gemini file, it will be passed through a template and the result will be written to the destination directory. -Any file or directory whose name begins with "\_" will be ignored. +Tasks can be configured to use different static content and output directories. +The content and template directories are shared between tasks. -# TEMPLATES -kiln looks for templates in the *templates* directory. -Templates use the Go templating language. -The following templates are supported: +# CONFIGURATION + +The configuration file uses the _TOML_ configuration file format. For more +information on TOML, see https://toml.io/en/v0.4.0. + +The following keys are supported: + +[[ *Key* +:[ *Description* +| title +: Site title +| urls +: A list of site URLs + +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. + +## CONTENT DIRECTORY + +The content directory contains content that should be processed before +being published. Any file or directory whose name begins with "\_" will be +ignored. + +Files in the content directory may be preprocessed, run through templates, and +postprocessed (in that order). Each operation takes the output of the last +operation as input. + +## STATIC CONTENT DIRECTORY + +All files in the static content directory will be copied to the output +directory without modification. Static assets like images should be stored in +this directory. + +## TEMPLATE DIRECTORY + +The template directory contains templates for use when building the site. +Templates use the Go templating language. The following templates are supported: [[ *Template* :[ *Description* @@ -44,13 +85,17 @@ The following templates are supported: : Directory index template | atom.xml : Atom feed template -| output.html -: HTML output template -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 src/blog. +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. +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. + +For more information on the Go templating language, see +https://golang.org/pkg/text/template/. ## FUNCTIONS @@ -63,7 +108,7 @@ All templates have the following functions available to them: ## SITE METADATA -Site metadata contains the following information: +Site metadata contains the following data: [[ *Variable* :[ *Description* @@ -76,7 +121,7 @@ To configure these variables, see *CONFIGURATION*. ## PAGE TEMPLATES -Page templates are provided with the following information: +Page templates are provided with the following data: [[ *Variable* :[ *Description* @@ -89,16 +134,17 @@ Page templates are provided with the following information: | Content : The contents of the page -Pages can specify dates in their filenames. -For example, src/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date of November 20, 2020. +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 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. ## INDEX TEMPLATES -Index templates are provided with the following information: +Index templates are provided with the following data: [[ *Variable* :[ *Description* @@ -113,14 +159,23 @@ Index templates are provided with the following information: | 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 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 default index template implements the lightweight subscription specification +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 are written to the directory path plus "atom.xml". ## FEED TEMPLATES -Atom feed templates are provided with the following information: +Feed templates are provided with the following data: [[ *Variable* :[ *Description* @@ -131,48 +186,5 @@ Atom feed templates are provided with the following information: | Entries : List of pages in this feed -Feeds are written to the directory path plus "atom.xml". - -The default feed template uses the site URLs, if present, to make relative links into absolute URLs. - -## HTML TEMPLATES - -HTML output templates are provided with the following information: - -[[ *Variable* -:[ *Description* -| Title -: Title of the page -| Content -: HTML contents of the page - -# CONFIGURATION - -kiln looks for a configuration file named "config.ini". - -The configuration file uses the _ini_ format. -A line beginning with ";" is considered a comment and ignored, as are empty lines. -New sections begin with [section-name] on a single line. -Keys and values are separated with "=". - -The following keys are supported: - -[[ *Key* -:[ *Description* -| title -: Site title -| url -: One or more site URLs separated by whitespace. - -Site URLs are used when generating Atom feeds. -Site URLs may contain paths, but should not end with a trailing slash. -Multiple site URLs may be specified if they are separated by whitespace. -This allows a site that is hosted on both Gemini and HTTP to specify URLs for both locations. - -The following sections are supported: - -[[ *Section* -:[ *Description* -| feeds -: A list of Atom feeds. Keys denote the path to the feed directory, and values denote the title of the feed. - +The default feed template uses the site URLs, if any, to turn relative links +into absolute URLs.