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

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, with the exception of pages with the name "_index" (e.g. "_index.gmi").

Pages may be preprocessed, run through templates, and postprocessed (in that order). Each operation takes the output of the last operation as input.

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

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:
  	custom: 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
  ---
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
urlsA 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.

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"

Tasks

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

The following configuration options are supported per task:

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

Specifies whether page permalinks will contain file extensions. By default, clean URLs 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 files in the content directory and HTML templates in the templates directory. This configuration makes use of the markdown(1) comand to convert Markdown to HTML.

  [[tasks]]
  input_ext = [".md"]
  output_ext = ".html"
  template_ext = ".html"
  preprocess.md = "markdown"
  static_dir = "static"
  output_dir = "public"

Templates

Templates have certain data and functions available to them.

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.

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.

Site Metadata

Site metadata contains the following data:

package main

import (

"fmt" "path"

)

func main() {

fmt.Println(path.Join("https://example.com", "hello-world"))

}

VariableDescription
TitleThe title of the site.
URLsThe URLs of the site.

To configure these variables, see Configuration.

Page Templates

Page templates are provided with the following data:

VariableDescription
TitleThe title of the page
DateThe date of the page
WeightThe weight of the page
PermalinkThe permanent link to this page
FilePathThe path of the page file relative to the content directory
ContentThe contents of the page
ParamsExtra parameters specified in frontmatter
PrevThe previous page in this directory
NextThe next page in this directory

Index Templates

Index templates are provided with all the data that page templates are provided, plus the following data:

VariableDescription
PagesList of pages in this directory
DirsList of subdirectories

Feed Templates

Feed templates are provided with the following data:

VariableDescription
TitleTitle of the feed
PermalinkThe permanent link to the feed directory
EntriesList of pages in this feed

Partial Templates

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

Info

2021-06-15