mirror of
https://git.sr.ht/~adnano/kiln
synced 2024-11-24 03:01:11 +00:00
179 lines
4.4 KiB
Markdown
179 lines
4.4 KiB
Markdown
kiln(1)
|
|
|
|
# NAME
|
|
|
|
kiln - a simple static site generator for Gemini sites
|
|
|
|
# SYNOPSIS
|
|
|
|
_kiln_ [--html]
|
|
|
|
# OPTIONS
|
|
|
|
\--format <format>
|
|
Specifies the output format to use. Supported formats include gemini and html. Defaults to "gemini".
|
|
|
|
# SITE STRUCTURE
|
|
|
|
A kiln site is structured in the following way:
|
|
|
|
[[ *Directory*
|
|
:[ *Description*
|
|
| content/
|
|
: Site source
|
|
| templates/
|
|
: Site templates
|
|
| public/
|
|
: Site 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.
|
|
| URLs
|
|
: The URLs 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 URLs, 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
|
|
: One or more site URLs separated by whitespace.
|
|
|
|
Site URLs are used when generating Atom feeds.
|
|
Site URLs may contain paths, but should not end with a trailing slash.
|
|
Multiple site URLs may be specified if they are separated by whitespace.
|
|
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.
|
|
|