kiln/doc/kiln.1.scd

kiln(1)

# NAME

kiln - a simple static site generator for Gemini sites

# SYNOPSIS

_kiln_ [--html]

# OPTIONS

\--html
	If this flag is present, kiln will output HTML as well as Gemini text.

# SITE STRUCTURE

A kiln site is structured in the following way:

[[ *Directory*
:[ *Description*
|  src/
:  Site source
|  templates/
:  Site templates
|  dst/
:  Site destination
|  html/
:  Site HTML 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.
|  URL
:  The URL 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 URL, 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
|  url
:  Site URL.

Site URLs are only used when generating Atom feeds.
Site URLs should not end with a trailing slash.
More than one site URL may be specified by specifying multiple url keys.
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.