kiln/doc/kiln.1.scd

kiln(1)

# NAME

kiln - a simple static site generator for Gemini sites

# SYNOPSIS

_kiln_ [--html]

# OPTIONS

\--format <format>
	Specifies the output format to use. Supported formats include gemini and html. Defaults to "gemini".

# SITE STRUCTURE

A kiln site is structured in the following way:

[[ *Directory*
:[ *Description*
|  content/
:  Site source
|  layouts/
:  Site templates
|  public/
:  Site destination

All files in the source directory will be copied to the destination directory.
If the file is a Gemini file, it will be passed through a template and the result will be written to the destination directory.
Any file or directory whose name begins with "\_" will be ignored.

# TEMPLATES

kiln looks for templates in the *templates* directory.
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
|  output.html
:  HTML output 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 src/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.

## FUNCTIONS

All templates have the following functions available to them:

[[ *Function*
:[ *Description*
|  site
:  Returns site metadata

## SITE METADATA

Site metadata contains the following information:

[[ *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 information:

[[ *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, src/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 information:

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

## FEED TEMPLATES

Atom feed templates are provided with the following information:

[[ *Variable*
:[ *Description*
|  Title
:  Title of the feed
|  Path
:  Path to the feed directory
|  Entries
:  List of pages in this feed

Feeds are written to the directory path plus "atom.xml".

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

## HTML TEMPLATES

HTML output templates are provided with the following information:

[[ *Variable*
:[ *Description*
|  Title
:  Title of the page
|  Content
:  HTML contents of the page

# CONFIGURATION

kiln looks for a configuration file named "config.ini".

The configuration file uses the _ini_ format.
A line beginning with ";" is considered a comment and ignored, as are empty lines.
New sections begin with [section-name] on a single line.
Keys and values are separated with "=".

The following keys are supported:

[[ *Key*
:[ *Description*
|  title
:  Site title
|  urls
:  A list of site URLs separated by whitespace.

Site URLs are used when generating Atom feeds.
Site URLs may contain paths, but should not end with a trailing slash.
Multiple site URLs may be specified if they are separated by whitespace.
This allows a site that is hosted on both Gemini and HTTP to specify URLs for both locations.

The following sections are supported:

[[ *Section*
:[ *Description*
|  feeds
:  A list of Atom feeds. Keys denote the path to the feed directory, and values denote the title of the feed.