kiln/docs/kiln.1.scd

kiln(1)

# NAME

kiln - a simple static site generator

# SYNOPSIS

*kiln* build [-c _config_]

*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".

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

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

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

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]]
	input = [".gmi"]
	output = ".gmi"
	template = ".gmi"
	static_dir = "static"
	output_dir = "public"

	# Export an HTML version of the site
	[[tasks]]
	input = [".gmi"]
	output = ".html"
	template = ".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]]
	input_ext = [".md"]
	output_ext = ".html"
	template_ext = ".html"
	preprocess.md = "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:

*site*
	Returns site metadata

*path.Base* _path_
	Returns the last element of path.

*path.Clean* _path_
	Returns the shortest path name equivalent to path.

*path.Dir* _path_
	Returns all but the last element of path, typically the path's directory.

*path.Ext* _path_
	Returns the filename extension used by path.

*path.Join* _elem..._
	Joins any number of path elements into a single path.

*safeHTML* _html_
	Encapsulates a known safe HTML document fragment.

*safeHTMLAttr* _attr_
	Encapsulates an HTML attribute from a trusted source.

*safeCSS* _css_
	Encapsulates known safe CSS content.

*safeJS* _js_
	Encapsulates a known safe JavaScript expression.

*safeURL* _url_
	Encapsulates a known safe URL or URL substring.

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