mirror of
https://git.sr.ht/~adnano/kiln
synced 2024-05-30 20:06:07 +02:00
297 lines
7.4 KiB
Markdown
297 lines
7.4 KiB
Markdown
kiln(1)
|
|
|
|
# NAME
|
|
|
|
kiln - a simple static site generator
|
|
|
|
# SYNOPSIS
|
|
|
|
*kiln* build++
|
|
[-c _config_]++
|
|
[-t _task_]
|
|
|
|
*kiln* new _path_
|
|
|
|
*kiln* version
|
|
|
|
# DESCRIPTION
|
|
|
|
*kiln build* builds a kiln site.
|
|
|
|
*kiln new* creates a new kiln site at the given path.
|
|
|
|
*kiln version* prints version information for the *kiln* program.
|
|
|
|
# OPTIONS
|
|
|
|
## kiln build
|
|
|
|
*-c* _config_
|
|
Specifies the configuration file to use. Defaults to "config.toml".
|
|
|
|
*-t* _task_
|
|
Specifies the task to run. Defaults to "all", which runs all tasks.
|
|
|
|
# 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/
|
|
: Content directory
|
|
| static/
|
|
: Static content directory
|
|
| templates/
|
|
: Template directory
|
|
| public/
|
|
: Output directory
|
|
|
|
Tasks can be configured to use different static content and output directories.
|
|
The content and template directories are shared between tasks.
|
|
|
|
# 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.
|
|
|
|
## TASKS
|
|
|
|
Tasks can be specified in the [tasks] table. Each task must have a unique name.
|
|
|
|
The following keys are supported per task:
|
|
|
|
|[ *Key*
|
|
:[ *Description*
|
|
| input_ext
|
|
: Input file extension
|
|
| output_ext
|
|
: Output file extension
|
|
| template_ext
|
|
: Template file extension
|
|
| preprocess
|
|
: Preprocess command
|
|
| postprocess
|
|
: Postprocess command
|
|
| static_dir
|
|
: Static content directory
|
|
| output_dir
|
|
: Output directory
|
|
|
|
The input file extension controls which files from the content directory to
|
|
process. Only files which have the same extension will be processed.
|
|
|
|
The output file extension controls the extension of the file that is written to
|
|
the output directory.
|
|
|
|
The template file extension specifies the extension of the templates that will
|
|
be used in the template directory. If unset, no templates will be used.
|
|
|
|
The static content directory controls which directory to use for static content.
|
|
If unset, no static content directory will be used.
|
|
|
|
The output directory specifies the directory to write the output files.
|
|
|
|
The preprocess command specifies a command which will run before the content is
|
|
passed to the template. It will be provided the content of the file as standard
|
|
input and should write the processed content to standard output.
|
|
|
|
The postprocess command specifies a command which will run after templating
|
|
and before the content is written to the output directory. It will be provided
|
|
the content of the file as standard input and should write the processed content
|
|
to standard output.
|
|
|
|
The following configuration generates a Gemini text site and also exports an
|
|
HTML version of the site. This configuration makes use of the *geminitohtml*(1)
|
|
command to convert Gemini text to HTML.
|
|
|
|
```
|
|
# Build the site
|
|
[tasks.gemini]
|
|
input_ext = ".gmi"
|
|
output_ext = ".gmi"
|
|
template_ext = ".gmi"
|
|
static_dir = "static"
|
|
output_dir = "public"
|
|
|
|
# Export an HTML version of the site
|
|
[tasks.geminitohtml]
|
|
input_ext = ".html"
|
|
output_ext = ".gmi"
|
|
template_ext = ".gmi"
|
|
postprocess = "geminitohtml"
|
|
static_dir = "static"
|
|
output_dir = "public.html"
|
|
```
|
|
|
|
The following configuration generates an HTML site from Markdown files in the
|
|
content directory and HTML templates in the template directory. This
|
|
configuration makes use of the *markdown*(1) comand to convert Markdown to HTML.
|
|
|
|
```
|
|
[tasks.markdowntohtml]
|
|
input_ext = ".md"
|
|
output_ext = ".html"
|
|
preprocess = "markdown"
|
|
static_dir = "static"
|
|
output_dir = "public"
|
|
```
|
|
|
|
## 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*
|
|
| page.gmi
|
|
: Page template
|
|
| index.gmi
|
|
: Directory index template
|
|
| atom.xml
|
|
: Atom feed 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
|
|
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.
|
|
|
|
For more information on the Go templating language, see
|
|
https://golang.org/pkg/text/template/.
|
|
|
|
## FUNCTIONS
|
|
|
|
All templates have the following functions available to them:
|
|
|
|
|[ *Function*
|
|
:[ *Description*
|
|
| site
|
|
: Returns site metadata
|
|
|
|
## SITE METADATA
|
|
|
|
Site metadata contains the following data:
|
|
|
|
|[ *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 data:
|
|
|
|
|[ *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, 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.
|
|
|
|
## INDEX TEMPLATES
|
|
|
|
Index templates are provided with the following data:
|
|
|
|
|[ *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.
|
|
|
|
## FEEDS
|
|
|
|
Feeds can 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 output directory plus the feed directory plus
|
|
"atom.xml".
|
|
|
|
Example feed configuration:
|
|
|
|
```
|
|
# This will generate a feed which will be written to public/blog/atom.xml
|
|
[feeds]
|
|
"/blog/" = "My blog"
|
|
```
|
|
|
|
## FEED TEMPLATES
|
|
|
|
Feed templates are provided with the following data:
|
|
|
|
|[ *Variable*
|
|
:[ *Description*
|
|
| Title
|
|
: Title of the feed
|
|
| Path
|
|
: Path to the feed directory
|
|
| Entries
|
|
: List of pages in this feed
|
|
|
|
The default feed template uses the site URLs, if any, to turn relative links
|
|
into absolute URLs.
|