mirror of
https://git.sr.ht/~adnano/kiln
synced 2024-11-24 03:01:11 +00:00
Update documentation
This commit is contained in:
adnano
parent
02ca7d1549
commit
68ae146361
168
doc/kiln.1.scd
168
doc/kiln.1.scd
|
|
@ -2,39 +2,80 @@ kiln(1)
|
|||
|
||||
# NAME
|
||||
|
||||
kiln - a simple static site generator for Gemini sites
|
||||
kiln - a simple static site generator
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
_kiln_ [--html]
|
||||
_kiln_ [-c <config>] [-t <task>]
|
||||
|
||||
# OPTIONS
|
||||
|
||||
\--format <format>
|
||||
Specifies the output format to use. Supported formats include gemini and html. Defaults to "gemini".
|
||||
\-c <config>
|
||||
Specifies the configuration file to use. Defaults to "config.toml".
|
||||
|
||||
# SITE STRUCTURE
|
||||
\-t <task>
|
||||
Specifies the task to run. Defaults to "all", which runs all tasks.
|
||||
|
||||
A kiln site is structured in the following way:
|
||||
# OVERVIEW
|
||||
|
||||
A kiln site is built in one or more steps called _tasks_.
|
||||
|
||||
There is only one default task called "gemini" which builds a Gemini site.
|
||||
|
||||
The following directories are used by default:
|
||||
|
||||
[[ *Directory*
|
||||
:[ *Description*
|
||||
| content/
|
||||
: Site source
|
||||
: Content directory
|
||||
| static/
|
||||
: Static content directory
|
||||
| templates/
|
||||
: Site templates
|
||||
: Template directory
|
||||
| public/
|
||||
: Site destination
|
||||
: Output directory
|
||||
|
||||
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.
|
||||
Tasks can be configured to use different static content and output directories.
|
||||
The content and template directories are shared between tasks.
|
||||
|
||||
# TEMPLATES
|
||||
|
||||
kiln looks for templates in the *templates* directory.
|
||||
Templates use the Go templating language.
|
||||
The following templates are supported:
|
||||
# CONFIGURATION
|
||||
|
||||
The configuration file uses the _TOML_ configuration file format. For more
|
||||
information on TOML, see https://toml.io/en/v0.4.0.
|
||||
|
||||
The following keys are supported:
|
||||
|
||||
[[ *Key*
|
||||
:[ *Description*
|
||||
| title
|
||||
: Site title
|
||||
| urls
|
||||
: A list of site URLs
|
||||
|
||||
Site URLs may contain paths, but should not end with a trailing slash. Multiple
|
||||
site URLs may be specified for sites that are available at multiple locations.
|
||||
|
||||
## CONTENT DIRECTORY
|
||||
|
||||
The content directory contains content that should be processed before
|
||||
being published. Any file or directory whose name begins with "\_" will be
|
||||
ignored.
|
||||
|
||||
Files in the content directory may be preprocessed, run through templates, and
|
||||
postprocessed (in that order). Each operation takes the output of the last
|
||||
operation as input.
|
||||
|
||||
## STATIC CONTENT DIRECTORY
|
||||
|
||||
All files in the static content directory will be copied to the output
|
||||
directory without modification. Static assets like images should be stored in
|
||||
this directory.
|
||||
|
||||
## TEMPLATE DIRECTORY
|
||||
|
||||
The template directory contains templates for use when building the site.
|
||||
Templates use the Go templating language. The following templates are supported:
|
||||
|
||||
[[ *Template*
|
||||
:[ *Description*
|
||||
|
|
@ -44,13 +85,17 @@ The following templates are supported:
|
|||
: 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.
|
||||
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
|
||||
content/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.
|
||||
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.
|
||||
|
||||
For more information on the Go templating language, see
|
||||
https://golang.org/pkg/text/template/.
|
||||
|
||||
## FUNCTIONS
|
||||
|
||||
|
|
@ -63,7 +108,7 @@ All templates have the following functions available to them:
|
|||
|
||||
## SITE METADATA
|
||||
|
||||
Site metadata contains the following information:
|
||||
Site metadata contains the following data:
|
||||
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
|
|
@ -76,7 +121,7 @@ To configure these variables, see *CONFIGURATION*.
|
|||
|
||||
## PAGE TEMPLATES
|
||||
|
||||
Page templates are provided with the following information:
|
||||
Page templates are provided with the following data:
|
||||
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
|
|
@ -89,16 +134,17 @@ Page templates are provided with the following information:
|
|||
| 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 dates in their filenames. For example, the file
|
||||
content/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.
|
||||
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:
|
||||
Index templates are provided with the following data:
|
||||
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
|
|
@ -113,14 +159,23 @@ Index templates are provided with the following information:
|
|||
| 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 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.
|
||||
The default index template implements the lightweight subscription specification
|
||||
found at gemini://gemini.circumlunar.space/docs/companion/subscription.gmi.
|
||||
|
||||
## FEEDS
|
||||
|
||||
Feeds can optionally be specified in the *feeds* table of the configuration file.
|
||||
Keys denote the path to the feed input directory and values denote the title of
|
||||
the feed.
|
||||
|
||||
Feeds are written to the directory path plus "atom.xml".
|
||||
|
||||
## FEED TEMPLATES
|
||||
|
||||
Atom feed templates are provided with the following information:
|
||||
Feed templates are provided with the following data:
|
||||
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
|
|
@ -131,48 +186,5 @@ Atom feed templates are provided with the following information:
|
|||
| 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.
|
||||
|
||||
The default feed template uses the site URLs, if any, to turn relative links
|
||||
into absolute URLs.
|
||||
|
|
|
|||
Loading…
Reference in a new issue