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 controls which files from the content directory to
process. Only files which have the same extension will be processed.

The output file extension controls 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 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 write the output files.

The preprocess command specifies a command which will run before the content is
passed to the template. It will be provided the content of the file 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 the content is written to the output directory. It will be provided
the content of the file as standard input and should write the processed content
to standard output.

The following configuration generates a Gemini text site and also exports an
HTML version of the site. This configuration makes use of the *geminitohtml*(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.geminitohtml]
	input_ext = ".html"
	output_ext = ".gmi"
	template_ext = ".gmi"
	postprocess = "geminitohtml"
	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"
	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.gmi
:  Page template
|  index.gmi
:  Directory index template
|  atom.xml
:  Atom feed 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
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.

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

## FEEDS

Feeds can 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 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

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

The default feed template uses the site URLs, if any, to turn relative links
into absolute URLs.