kiln/doc/kiln.1.scd

kiln(1)

# NAME

kiln - a simple static site generator

# SYNOPSIS

_kiln_ [-c <config>] [-t <task>]

# OPTIONS

\-c <config>
	Specifies the configuration file to use. Defaults to "config.toml".

\-t <task>
	Specifies the task to run. Defaults to "all", which runs all tasks.

# 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/
:  Content directory
|  static/
:  Static content directory
|  templates/
:  Template directory
|  public/
:  Output directory

Tasks can be configured to use different static content and output directories.
The content and template directories are shared between tasks.

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

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.