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

# TEMPLATES

kiln looks for templates in the *templates* directory.
The following templates are supported:

[[ *Template*
:[ *Description*
|  page.gmi
:  Page template
|  index.gmi
:  Directory index template
|  feed.gmi
:  Gemini feed template
|  output.html
:  HTML output template

The scope of templates can be limited by placing them in subdirectories of the templates directory.
For example, the template templates/blog/page.gmi will apply to all pages in src/blog.

## 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, which can be specified in the site 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.

## FEED TEMPLATES

Feed templates are provided with the following information:

[[ *Variable*
:[ *Description*
|  Title
:  Title of the feed
|  Path
:  Path to the feed directory
|  Entries
:  List of feed entries

Feeds are written to the directory path plus "feed".

## 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.
The following keys are supported:

[[ *Key*
:[ *Description*
|  title
:  Site title

The following sections are supported:

[[ *Section*
:[ *Description*
|  feeds
:  A list of feeds. Each key denotes a path to a directory, and each value
   denotes the title of the feed.