kiln(1) # NAME kiln - a simple static site generator # SYNOPSIS *kiln* build++ [-c _config_]++ [-t _task_] *kiln* new _path_ *kiln* version # DESCRIPTION *kiln build* builds a kiln site. *kiln new* creates a new kiln site at the given path. *kiln version* prints version information for the *kiln* program. # OPTIONS ## kiln build *-c* _config_ Specifies the configuration file to use. Defaults to "config.toml". *-t* _task_ Specifies the task to run. If unspecified, all tasks will be run. # 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. The following directories are common to all tasks: [[ *Directory* :[ *Description* | content/ : Content directory | templates/ : Templates directory # CONTENT DIRECTORY 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. 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. ## 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. Example: ``` --- title: Page title date: 2021-04-24 params: custom: value --- Page content ``` The following keys are supported: [[ *Key* :[ *Description* | title : Page title | date : Page date | params : Extra parameters to be passed to templates # TEMPLATES DIRECTORY The templates directory contains templates for use when building the site. Templates use the Go templating language. The following templates are supported: [[ *Template* :[ *Description* | page.ext : Page template | index.ext : Directory index template | atom.xml : Atom feed template The extension of page and index templates is configurable and will replace ".ext" above. See *CONFIGURATION*. The scope of a template is limited by the directory it is placed in. For 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. For more information on the Go templating language, see https://golang.org/pkg/text/template/. # CONFIGURATION 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. 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. ## FEEDS Feeds can be specified in the [feeds] table of the configuration file. Keys 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". Example feed configuration: ``` # This will generate a feed which will be written to public/blog/atom.xml [feeds] "/blog/" = "My blog" ``` ## 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 specifies which files from the content directory to process. Only files which have the same extension will be processed. 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 templates 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. All files in this directory will be copied to the output directory without modification. Static assets like images should be stored in this directory. 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 *gmnitohtml*(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.exporthtml] input_ext = ".gmi" output_ext = ".html" template_ext = ".gmi" postprocess = "gmnitohtml" 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 templates directory. This 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" ``` # TEMPLATES Templates have certain data and functions available to them. ## TEMPLATE FUNCTIONS All templates have the following functions available to them: [[ *Function* :[ *Description* | site : Returns site metadata ## SITE METADATA Site metadata contains the following data: [[ *Variable* :[ *Description* | Title : The title of the site. | URLs : The URLs of the site. To configure these variables, see *CONFIGURATION*. ## PAGE TEMPLATES Page templates are provided with the following data: [[ *Variable* :[ *Description* | Title : The title of the page | Date : The date of the page | Path : Path to the page | Content : The contents of the page | Params : Extra parameters specified in frontmatter ## INDEX TEMPLATES Index templates are provided with all the data that page templates are provided, plus the following data: [[ *Variable* :[ *Description* | Pages : List of pages in this directory | Dirs : List of subdirectories ## FEED TEMPLATES Feed templates are provided with the following data: [[ *Variable* :[ *Description* | Title : Title of the feed | Path : Path to the feed directory | Entries : List of pages in this feed