kiln/doc/kiln.1.scd

148 lines
2.8 KiB
Plaintext
Raw Normal View History

2020-11-11 00:35:56 +00:00
kiln(1)
# NAME
kiln - a simple static site generator for Gemini sites
# SYNOPSIS
2020-11-20 17:07:38 +00:00
_kiln_ [--html]
# OPTIONS
\--html
If this flag is present, kiln will output HTML as well as Gemini text.
2020-11-11 00:35:56 +00:00
# SITE STRUCTURE
2020-11-20 17:07:38 +00:00
A kiln site is structured in the following way:
2020-11-11 00:35:56 +00:00
2020-11-20 17:07:38 +00:00
[[ *Directory*
2020-11-11 00:35:56 +00:00
:[ *Description*
| src/
: Site source
| templates/
2020-11-20 17:07:38 +00:00
: Site templates
2020-11-11 00:35:56 +00:00
| dst/
: Site destination
2020-11-20 17:07:38 +00:00
| html/
2020-11-11 00:35:56 +00:00
: Site HTML destination
# TEMPLATES
2020-11-20 17:07:38 +00:00
kiln looks for templates in the *templates* directory.
The following templates are supported:
2020-11-11 00:35:56 +00:00
2020-11-20 17:07:38 +00:00
[[ *Template*
2020-11-11 00:35:56 +00:00
:[ *Description*
| page.gmi
: Page template
| index.gmi
: Directory index template
2020-11-20 17:07:38 +00:00
| feed.gmi
: Gemini feed template
2020-11-11 00:35:56 +00:00
| output.html
2020-11-20 17:07:38 +00:00
: 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.
2020-11-11 00:35:56 +00:00
## PAGE TEMPLATES
Page templates are provided with the following information:
2020-11-20 17:07:38 +00:00
[[ *Variable*
2020-11-11 00:35:56 +00:00
:[ *Description*
| Title
: The title of the page
| Date
: The date of the page
2020-11-20 17:07:38 +00:00
| Path
: Path to the page
2020-11-11 00:35:56 +00:00
| Content
: The contents of the page
Pages can specify dates in their filenames.
2020-11-20 17:07:38 +00:00
For example, src/2020-11-20-Hello-world.gmi will have a path of /Hello-world and a date of November 20, 2020.
2020-11-11 00:35:56 +00:00
2020-11-20 17:07:38 +00:00
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.
2020-11-11 00:35:56 +00:00
## INDEX TEMPLATES
Index templates are provided with the following information:
2020-11-20 17:07:38 +00:00
[[ *Variable*
2020-11-11 00:35:56 +00:00
:[ *Description*
2020-11-20 17:07:38 +00:00
| Path
: Path to the directory
2020-11-11 00:35:56 +00:00
| Pages
: List of pages in this directory
2020-11-20 17:07:38 +00:00
| Dirs
2020-11-11 00:35:56 +00:00
: List of subdirectories
2020-11-20 17:07:38 +00:00
## FEED TEMPLATES
2020-11-11 00:35:56 +00:00
2020-11-20 17:07:38 +00:00
Feed templates are provided with the following information:
2020-11-11 00:35:56 +00:00
2020-11-20 17:07:38 +00:00
[[ *Variable*
:[ *Description*
| Title
: Title of the feed
| Path
: Path to the feed directory
| Entries
: List of feed entries
2020-11-11 00:35:56 +00:00
2020-11-20 17:07:38 +00:00
Feeds are written to the directory path plus "feed".
2020-11-11 00:35:56 +00:00
2020-11-20 17:07:38 +00:00
## HTML TEMPLATES
HTML output templates are provided with the following information:
[[ *Variable*
2020-11-11 00:35:56 +00:00
:[ *Description*
2020-11-20 17:07:38 +00:00
| Title
: Title of the page
| Content
: HTML contents of the page
2020-11-11 00:35:56 +00:00
# CONFIGURATION
kiln looks for a configuration file named "config.ini".
The configuration file uses the _ini_ format.
The following keys are supported:
2020-11-20 17:07:38 +00:00
[[ *Key*
2020-11-11 00:35:56 +00:00
:[ *Description*
| title
: Site title
2020-11-20 17:07:38 +00:00
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.
2020-11-11 00:35:56 +00:00