kiln/docs/kiln.1.scd

360 lines
8.8 KiB
Plaintext
Raw Normal View History

2020-11-11 00:35:56 +00:00
kiln(1)
# NAME
2021-04-12 04:23:27 +00:00
kiln - a simple static site generator
2020-11-11 00:35:56 +00:00
# SYNOPSIS
2021-05-10 19:09:23 +00:00
*kiln* build [-c _config_]
2021-04-20 20:00:39 +00:00
*kiln* new _path_
*kiln* version
# DESCRIPTION
*kiln build* builds a kiln site.
*kiln new* creates a new kiln site at the given path.
2021-05-10 19:09:23 +00:00
*kiln version* prints version information for the kiln program.
2020-11-20 17:07:38 +00:00
# OPTIONS
2021-04-20 20:00:39 +00:00
## kiln build
*-c* _config_
2021-04-12 04:23:27 +00:00
Specifies the configuration file to use. Defaults to "config.toml".
2020-11-11 00:35:56 +00:00
2021-04-12 04:23:27 +00:00
# OVERVIEW
2021-04-26 18:49:39 +00:00
A kiln site is built in one or more steps called *tasks*.
2021-04-21 01:37:05 +00:00
Tasks read content from the content directory, process the content, and write
the content to the output directory. Tasks can also be configured to copy static
content to the output directory.
2021-04-12 04:23:27 +00:00
2021-04-21 01:37:05 +00:00
The following directories are common to all tasks:
2020-11-11 00:35:56 +00:00
2021-04-24 18:11:22 +00:00
[[ *Directory*
2020-11-11 00:35:56 +00:00
:[ *Description*
2021-02-28 17:17:10 +00:00
| content/
2021-04-12 04:23:27 +00:00
: Content directory
2021-03-20 06:18:15 +00:00
| templates/
2021-04-26 18:49:39 +00:00
: Templates directory
# CONTENT DIRECTORY
The content directory contains site content files, called *pages*, optionally
nested in subdirectories. Any file or directory in the content directory whose
name begins with "\_" will be ignored.
Pages may be preprocessed, run through templates, and postprocessed (in that
order). Each operation takes the output of the last operation as input.
; TODO: Should we remove this behavior and opt for using frontmatter instead?
Pages can specify dates in their filenames. For example, the page
content/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date
of November 20, 2020.
Pages with the name "index" are index pages and are treated specially.
## FRONTMATTER
Content files can specify additional metadata in frontmatter. Frontmatter is
delimited by "---" and is specified in YAML. Newlines after the closing
delimiter are removed from the content.
Example:
```
---
title: Page title
date: 2021-04-24
params:
custom: value
---
Page content
```
The following keys are supported:
[[ *Key*
:[ *Description*
| title
: Page title
| date
: Page date
| params
: Extra parameters to be passed to templates
# TEMPLATES DIRECTORY
The templates directory contains templates for use when building the site.
Templates use the Go templating language. The following templates are supported:
[[ *Template*
:[ *Description*
| page.ext
: Page template
| index.ext
: Directory index template
| atom.xml
: Atom feed template
The extension of page and index templates is configurable and will replace
".ext" above. See *CONFIGURATION*.
The scope of a template is limited by the directory it is placed in. For
example, a template in the templates/blog directory will only apply to files in
content/blog.
Fallback templates can be specified in the templates/\_default directory. These
templates will apply to any files which do not have their own templates
specified.
For more information on the Go templating language, see
https://golang.org/pkg/text/template/.
2021-04-12 04:23:27 +00:00
# CONFIGURATION
2020-11-11 00:35:56 +00:00
2021-04-26 18:49:39 +00:00
By default, kiln looks for a configuration file named "config.toml". An
alternative configuration file can be specified with the *-c* flag. See
*OPTIONS*.
2021-05-10 19:43:04 +00:00
The configuration file uses the _TOML_ configuration file format.
2020-11-22 20:51:07 +00:00
2021-04-12 04:23:27 +00:00
The following keys are supported:
2021-04-24 18:11:22 +00:00
[[ *Key*
2021-04-12 04:23:27 +00:00
:[ *Description*
| title
: Site title
| urls
: A list of site URLs
2020-11-11 00:35:56 +00:00
2021-04-12 04:23:27 +00:00
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.
2021-04-26 18:49:39 +00:00
## FEEDS
Feeds can be specified in the [feeds] table of the configuration file. Keys
denote the path to the feed 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"
```
2021-05-14 04:28:41 +00:00
## PERMALINKS
Permalinks can be used to rewrite page paths. Permalinks are specified in the
\[permalinks] table of the configuration file. Keys denote a path to a directory,
2021-05-14 04:28:41 +00:00
and values use the Go templating language to rewrite the final path of pages in
that directory. The templates have the same data that page templates have
available to them (see *PAGE TEMPLATES*).
The following configuration will rewrite the paths of pages in the content/blog
directory to /YYYY/MM/DD/slug. For example, the file
content/blog/2021-05-12-hello-world.gmi will have a path of
/2021/05/12/hello-world/.
```
[permalinks]
"/blog/" = "/{{ .Date.Format `2006/01/02` }}/{{ path.Base .Path }}"
```
For more information on templates, see *TEMPLATES*.
2021-04-12 15:09:14 +00:00
## TASKS
Tasks can be specified in the [tasks] table. Each task must have a unique name.
The following keys are supported per task:
2021-04-24 18:11:22 +00:00
[[ *Key*
2021-04-12 15:09:14 +00:00
:[ *Description*
2021-05-10 16:47:38 +00:00
| input
: Input file extensions
| output
2021-04-12 15:09:14 +00:00
: Output file extension
2021-05-10 16:47:38 +00:00
| template
2021-04-12 15:09:14 +00:00
: Template file extension
| preprocess
2021-05-10 16:47:38 +00:00
: Preprocess commands
2021-04-12 15:09:14 +00:00
| postprocess
: Postprocess command
| static_dir
: Static content directory
| output_dir
: Output directory
2021-04-24 18:11:22 +00:00
The input file extension specifies which files from the content directory to
2021-04-12 15:09:14 +00:00
process. Only files which have the same extension will be processed.
2021-04-24 18:11:22 +00:00
The output file extension specifies the extension of the file that is written to
2021-04-12 15:09:14 +00:00
the output directory.
The template file extension specifies the extension of the templates that will
2021-04-26 18:49:39 +00:00
be used in the templates directory. If unset, no templates will be used.
2021-04-12 15:09:14 +00:00
2021-05-10 16:47:38 +00:00
The preprocess commands specify commands which will run before content is
2021-04-24 18:11:22 +00:00
passed to a template. It will be provided the content as standard input and
should write the processed content to standard output.
2021-04-12 15:09:14 +00:00
2021-04-24 18:11:22 +00:00
The postprocess command specifies a command which will run after templating
and before content is written to the output directory. It will be provided the
content as standard input and should write the content to standard output.
2021-04-12 15:09:14 +00:00
2021-04-24 18:11:22 +00:00
The static content directory controls which directory to use for static content.
2021-04-26 18:49:39 +00:00
If unset, no static content directory will be used. All files in this directory
will be copied to the output directory without modification. Static assets like
images should be stored in this directory.
2021-04-12 15:09:14 +00:00
2021-04-24 18:11:22 +00:00
The output directory specifies the directory to which the output files will be
written.
2021-04-12 15:09:14 +00:00
The following configuration generates a Gemini text site and also exports an
2021-04-24 18:11:22 +00:00
HTML version of the site. This configuration makes use of the *gmnitohtml*(1)
2021-04-12 15:09:14 +00:00
command to convert Gemini text to HTML.
```
# Build the site
2021-05-10 19:09:23 +00:00
[[tasks]]
2021-05-10 16:47:38 +00:00
input = [".gmi"]
output = ".gmi"
template = ".gmi"
2021-04-12 15:09:14 +00:00
static_dir = "static"
output_dir = "public"
# Export an HTML version of the site
2021-05-10 19:09:23 +00:00
[[tasks]]
2021-05-10 16:47:38 +00:00
input = [".gmi"]
output = ".html"
template = ".gmi"
2021-04-24 18:11:22 +00:00
postprocess = "gmnitohtml"
2021-04-12 15:09:14 +00:00
static_dir = "static"
output_dir = "public.html"
```
The following configuration generates an HTML site from Markdown files in the
2021-04-26 18:49:39 +00:00
content directory and HTML templates in the templates directory. This
2021-04-12 15:09:14 +00:00
configuration makes use of the *markdown*(1) comand to convert Markdown to HTML.
```
2021-05-10 19:09:23 +00:00
[[tasks]]
2021-05-10 16:47:38 +00:00
input_ext = [".md"]
2021-04-12 15:09:14 +00:00
output_ext = ".html"
2021-04-24 18:11:22 +00:00
template_ext = ".html"
2021-05-10 16:47:38 +00:00
preprocess.md = "markdown"
2021-04-12 15:09:14 +00:00
static_dir = "static"
output_dir = "public"
```
2021-04-26 18:49:39 +00:00
# TEMPLATES
2021-04-24 18:11:22 +00:00
2021-04-26 18:49:39 +00:00
Templates have certain data and functions available to them.
2021-04-12 04:23:27 +00:00
2021-04-26 18:49:39 +00:00
## TEMPLATE FUNCTIONS
2020-11-20 17:07:38 +00:00
All templates have the following functions available to them:
2021-05-10 16:47:38 +00:00
*site*
Returns site metadata
2021-05-17 15:52:54 +00:00
*reverse* _list_
Returns a reversed copy of the provided slice or array.
2021-05-10 16:47:38 +00:00
*path.Base* _path_
Returns the last element of path.
*path.Clean* _path_
Returns the shortest path name equivalent to path.
*path.Dir* _path_
Returns all but the last element of path, typically the path's directory.
*path.Ext* _path_
Returns the filename extension used by path.
*path.Join* _elem..._
Joins any number of path elements into a single path.
*safeHTML* _html_
Encapsulates a known safe HTML document fragment.
*safeHTMLAttr* _attr_
Encapsulates an HTML attribute from a trusted source.
*safeCSS* _css_
Encapsulates known safe CSS content.
*safeJS* _js_
Encapsulates a known safe JavaScript expression.
*safeURL* _url_
Encapsulates a known safe URL or URL substring.
2020-11-20 17:07:38 +00:00
## SITE METADATA
2021-04-12 04:23:27 +00:00
Site metadata contains the following data:
2020-11-20 17:07:38 +00:00
2021-04-24 18:11:22 +00:00
[[ *Variable*
2020-11-20 17:07:38 +00:00
:[ *Description*
| Title
2020-11-22 20:51:07 +00:00
: The title of the site.
2020-12-21 21:41:05 +00:00
| URLs
: The URLs of the site.
2020-11-22 20:51:07 +00:00
To configure these variables, see *CONFIGURATION*.
2020-11-11 00:35:56 +00:00
## PAGE TEMPLATES
2021-04-12 04:23:27 +00:00
Page templates are provided with the following data:
2020-11-11 00:35:56 +00:00
2021-04-24 18:11:22 +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
2021-04-26 18:49:39 +00:00
| Params
: Extra parameters specified in frontmatter
2020-11-11 00:35:56 +00:00
## INDEX TEMPLATES
2021-04-26 18:49:39 +00:00
Index templates are provided with all the data that page templates are provided,
plus the following data:
2020-11-11 00:35:56 +00:00
2021-04-24 18:11:22 +00:00
[[ *Variable*
2020-11-11 00:35:56 +00:00
:[ *Description*
| 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
2021-04-26 18:49:39 +00:00
Feed templates are provided with the following data:
2020-11-11 00:35:56 +00:00
2021-04-24 18:11:22 +00:00
[[ *Variable*
2020-11-20 17:07:38 +00:00
:[ *Description*
| Title
: Title of the feed
| Path
: Path to the feed directory
| Entries
2020-11-22 20:51:07 +00:00
: List of pages in this feed
2020-11-11 00:35:56 +00:00