kiln/doc/kiln.1.scd
2020-11-20 12:07:38 -05:00

148 lines
2.8 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
# 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*
| Path
: Path to the directory
| Pages
: List of pages in this directory
| Dirs
: List of subdirectories
## 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.