kiln - Man Page

a simple static site generator

Synopsis

kiln build [-c config]

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".

Overview

A kiln site is built in one or more steps called tasks. 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.

The following directories are common to all tasks:

DirectoryDescription
content/Content directory
templates/Templates directory

The basic unit of a kiln site is the page. Each page either represents a content file or a subdirectory containing other pages. Pages may be preprocessed, run through templates, and postprocessed (in that order). Each operation takes the output of the last operation as input.

Content Directory

The content directory contains site content files which can be nested in subdirectories. Any file or directory in the content directory whose name begins with "_" will be ignored, with the exception of files with the name "_index" (e.g. "_index.gmi").

Content files can specify dates in their filenames. For example, the file content/2020-11-20-Hello-world.gmi will result in a page with a path of /Hello-world/ and a date of November 20, 2020.

Files with the name "_index" are treated specially. They can be used to provide frontmatter and content for the parent directory which will otherwise have none. If an "_index" file is present in a directory, an index page (e.g. "index.gmi") for that directory will be generated and written to the output directory.

Frontmatter

Pages 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:
    key: value
  ---

Page content

The following keys are supported:

title

The title of the page.

Example:

  ---
  title: My first post
  ---
date

The date of the page. Pages are sorted by date in reverse order, so newer pages will be placed above older pages.

Example:

  ---
  date: 2021-05-21
  ---
weight

The weight of the page. Pages are sorted by weight in increasing order, so pages with a smaller weight will be placed above pages with a larger weight.

Example:

  ---
  weight: 1
  ---
outputs

Optionally specifies a list of tasks that can build this page. Defaults to all tasks.

Example:

  ---
  outputs: ["Gemini", "HTTPS"]
  ---

---
outputs: [] # Excluded from all tasks
---
params

Specifies extra parameters to be provided to templates.

Example:

  ---
  params:
    key: value
  ---

Sorting

Pages are sorted automatically. Pages are first ordered by weight in increasing order, then by date from newest to oldest, and then by filename in alphabetical order.

Templates Directory

The templates directory contains templates for use when building the site. Templates use the Go templating language. The following templates are supported:

TemplateDescription
page.extPage template
index.extDirectory index template
base.extBase template from which the page and index templates inherit
atom.xmlAtom 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 directory which does not have its own templates specified in the template directory.

For more information on the Go templating language, see https://golang.org/pkg/text/template/.

Configuration

By default, kiln looks for a configuration file named "config.toml". An alternative configuration file can be specified with the -c flag. See Options.

The configuration file uses the TOML format.

The following keys are supported:

KeyDescription
titleSite title
paramsExtra parameters made available to templates

Tasks

Tasks can be specified in the [[tasks]] array of tables.

The following configuration options are supported per task:

name

An optional name for the task.

Example:

  [[tasks]]
  name = "Gemini"

[[tasks]]
name = "HTML export"
input

A list of input file extensions. Files in the content directory with a matching extension will be processed.

Example:

  [[tasks]]
  input = [".gmi", ".md"]
output

The output file extension. Files written to the output directory will use this extension.

Example:

  [[tasks]]
  output = ".html"
template

The template file extension. Templates with this file extension will be used to format the content. If unset, no templates will be used.

Example:

  [[tasks]]
  template = ".gmi"
preprocess

Maps file extensions to preprocess commands. Preprocess commands will run before templating. The commands will be provided the content of the page as standard input and should write the processed content to standard output.

Example:

  [[tasks]]
  input = [".gmi", ".md"]
  output = ".html"
  preprocess.gmi = "gmnitohtml"
  preprocess.md = "mdtohtml"
postprocess

Specifies a command which will run after templating and before content is written to the output directory. It will be provided the content of the page as standard input and should write the processed content to standard output.

Example:

  [[tasks]]
  input = [".gmi"]
  output = ".html"
  template = ".gmi"
  postprocess = "gmnitohtml"
static_dir

Specifies a directory from which to read static content. All files in this directory will be copied to the output directory without modificiation. Static assets like images should be stored in this directory. If unset, no static content directory will be used.

Example:

  [[tasks]]
  static_dir = "static"
output_dir

Specifies the directory to which output files will be written.

Example:

  [[tasks]]
  output_dir = "public"
url

The base URL to use for page URLs. The base URL should not have trailing forward slashes.

ugly_urls

Specifies whether page paths will contain file extensions. By default, clean paths without any extension are used.

Example:

  [[tasks]]
  ugly_urls = true

The following configuration builds a simple Gemini site.

  [[tasks]]
  input = [".gmi"]
  output = ".gmi"
  template = ".gmi"
  output_dir = "public"

The following configuration generates a Gemini text site and also exports an HTML version of the site. This configuration makes use of the gmnitohtml(1) command to convert Gemini text to HTML.

  # Build the site
  [[tasks]]
  input = [".gmi"]
  output = ".gmi"
  template = ".gmi"
  static_dir = "static"
  output_dir = "public"

# Export an HTML version of the site
[[tasks]]
input = [".gmi"]
output = ".html"
template = ".gmi"
postprocess = "gmnitohtml"
static_dir = "static"
output_dir = "public_html"

The following configuration generates an HTML site from Markdown and Gemini text files in the content directory and HTML templates in the templates directory. This configuration makes use of the mdtohtml(1) command to convert Markdown to HTML, and the gmnitohtml(1) command to convert Gemini text to HTML.

  [[tasks]]
  input = [".md", ".gmi"]
  output = ".html"
  template = ".html"
  preprocess.md = "mdtohtml"
  preprocess.gmi = "gmnitohtml"
  static_dir = "static"
  output_dir = "public"

Feeds

Feeds can be specified in the [[tasks.feeds]] array of tables. Multiple feeds can be specified per task.

Example feed configuration:

  [[tasks]]
  # ...

# This generates a feed for the files in content/blog
# and writes it to blog/atom.xml (relative to the output directory)
[[tasks.feeds]]
input_dir = "blog"
title = "My Blog"
template = "atom.xml"
output = "blog/atom.xml"

# You can generate multiple feeds per task
# The generated feed can be written anywhere
# Here it is written to feed.xml (relative to the output directory)
[[tasks.feeds]]
input_dir = "blog"
title = "My Blog"
template = "custom_feed.xml"
output = "feed.xml"
input_dir

the content folder with which to populate the feed

title

the title of the feed, accessible via {{ .Title }} in the feed template

template

the template to use for the feed

output

the output path for the rendered feed

Templates

Templates have certain data and functions available to them.

Site Metadata

Site metadata contains the following data:

Title

The title of the site.

Params

Extra parameters specified in configuration.

Generated

Site generation time.

Root

The root page of the site.

Site metadata can be accessed from templates with the site function. See Template Functions.

To configure these variables, see Configuration.

Page Templates

Page and index templates are provided with the following data:

Title

The title of the page

Date

The date of the page

Weight

The weight of the page

Path

The path to the page

URL

The URL of the page. If no base URL is configured, it is equivalent to Path.

FilePath

The path of the page file or directory relative to the content directory

Content

The contents of the page

Params

Extra parameters specified in frontmatter

Prev

The previous page in sorted order

Next

The next page in sorted order

Pages

List of pages in this directory

Dirs

List of subdirectories in this directory

Feed Templates

Feed templates are provided with the following data:

Title

Title of the feed

Path

The path to the feed directory

URL

The URL of the feed directory

Pages

List of pages in this feed

Partial Templates

Partial templates can be placed in the templates/_partials directory. Partial templates can be executed from any other template with the partial function. See Template Functions.

Template Functions

All templates have the following functions available to them:

and args...

Returns the boolean AND of its arguments by returning the first empty argument or the last argument, that is, "and x y" behaves as "if x then y else x". All the arguments are evaluated.

call function, args...

Returns the result of calling the first argument, which must be a function, with the remaining arguments as parameters. Thus "call .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where Y is a func-valued field, map entry, or the like. The first argument must be the result of an evaluation that yields a value of function type (as distinct from a predefined function such as print). The function must return either one or two result values, the second of which is of type error. If the arguments don't match the function or the returned error value is non-nil, execution stops.

eq arg1, arg2

Returns the boolean truth of arg1 == arg2.

exec command, input

Executes the given external command with input provided as standard input. Returns its standard output.

ge arg1, arg2

Returns the boolean truth of arg1 >= arg2.

gt arg1, arg2

Returns the boolean truth of arg1 > arg2.

html args...

Returns the escaped HTML equivalent of the textual representation of its arguments. This function is unavailable in HTML templates, with a few exceptions.

index collection, args...

Returns the result of indexing its first argument by the following arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each indexed item must be a map, slice, or array.

js args...

Returns the escaped JavaScript equivalent of the textual representation of its arguments.

le arg1, arg2

Returns the boolean truth of arg1 <= arg2.

len list

Returns the integer length of its argument.

lt arg1, arg2

Returns the boolean truth of arg1 < arg2.

ne arg1, arg2

Returns the boolean truth of arg1 != arg2.

not arg

Returns the boolean negation of its single argument.

or args...

Returns the boolean OR of its arguments by returning the first non-empty argument or the last argument, that is, "or x y" behaves as "if x then x else y". All the arguments are evaluated.

partial name, data

Executes the named partial template with the provided data. See Partial Templates.

Example:

  {{ partial "header.gmi" . }}
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.

print args...

Formats using the default formats for its operands and returns the resulting string. Spaces are added between operands when neither is a string.

printf format, args...

Formats according to a format specifier and returns the resulting string.

println args...

Formats using the default formats for its operands and returns the resulting string. Spaces are always added between operands and a newline is appended.

reverse list

Returns a reversed copy of the provided slice or array.

safeCSS css

Encapsulates known safe CSS content.

safeHTML html

Encapsulates a known safe HTML document fragment.

safeHTMLAttr attr

Encapsulates an HTML attribute from a trusted source.

safeJS js

Encapsulates a known safe JavaScript expression.

safeURL url

Encapsulates a known safe URL or URL substring.

site

Returns site metadata (see Site Metadata).

slice list, args...

slice returns the result of slicing its first argument by the remaining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2], while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3" is x[1:2:3]. The first argument must be a string, slice, or array.

strings.Count string, substr

Counts the number of non-overlapping instances of substr in string. If substr is an empty string, Count returns 1 + the number of Unicode code points in string.

strings.HasPrefix string, prefix

Reports whether string begins with prefix.

strings.HasSuffix string, suffix

Reports whether string ends with suffix.

strings.Join elems, sep

Concatenates the elements of its first argument to create a single string. The separator string sep is placed between elements in the resulting string.

strings.Repeat string, count

Returns a new string consisting of count copies of string.

It panics if count is negative or if the result of (len(string) * count) overflows.

strings.Replace string, old, new, n

Returns a copy of string with the first n non-overlapping instances of old replaced by new. If old is empty, it matches at the beginning of the string and after each UTF-8 sequence, yielding up to k+1 replacements for a k-rune string. If n < 0, there is no limit on the number of replacements.

strings.ReplaceAll string, old, new

Returns a copy of string with all non-overlapping instances of old replaced by new. If old is empty, it matches at the beginning of the string and after each UTF-8 sequence, yielding up to k+1 replacements for a k-rune string.

strings.Split string, sep

Slices string into all substrings separated by sep and returns a slice of the substrings between those separators.

If string does not contain sep and sep is not empty, Split returns a slice of length 1 whose only element is string.

If sep is empty, Split splits after each UTF-8 sequence. If both string and sep are empty, Split returns an empty slice.

strings.Title string

Returns a copy of the string with all Unicode letters that begin words mapped to their Unicode title case.

BUG: The rule Title uses for word boundaries does not handle Unicode punctuation properly.

strings.ToLower string

Returns string with all Unicode letters mapped to their lower case.

strings.ToUpper string

Returns string with all Unicode letters mapped to their upper case.

strings.Trim string, cutset

Returns a slice of string with all leading and trailing Unicode code points contained in cutset removed.

strings.TrimLeft string, cutset

Returns a slice of string with all leading Unicode code points contained in cutset removed.

To remove a prefix, use strings.TrimPrefix instead.

strings.TrimPrefix string, prefix

Returns string without the provided leading prefix string. If string doesn't start with prefix, it is returned unchanged.

strings.TrimRight string, cutset

Returns a slice of string with all trailing Unicode code points contained in cutset removed.

To remove a suffix, use strings.TrimSuffix instead.

strings.TrimSpace string

Returns a slice of string with all leading and trailing white space removed, as defined by Unicode.

strings.TrimSuffix string, suffix

Returns string without the provided trailing suffix string. If string doesn't end with suffix, it is returned unchanged.

urlquery args...

Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. This function is unavailable in HTML templates, with a few exceptions.

Info

2022-07-21