kiln/docs/kiln.1.scd

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/
:  Template directory

# 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.

## 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 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 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 = ".html"
	output_ext = ".gmi"
	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 template 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"
	```

## 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*
|  page.ext
:  Page template
|  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.

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/.

## 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

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 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*
:[ *Description*
|  Title
:  Title of the directory
|  Content
:  The contents of the directory index file
|  Path
:  Path to the directory
|  Pages
:  List of pages in this directory
|  Dirs
:  List of subdirectories

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 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"
	```

## FEED TEMPLATES

Atom 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