kiln/doc/kiln.1.scd
2020-11-22 15:55:06 -05:00

171 lines
3.7 KiB
Markdown

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
Any file or directory whose name begins with "\_" will be ignored.
# 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
| 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".
## 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. Should not end with a trailing slash.
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.