mirror of
https://git.sr.ht/~adnano/kiln
synced 2024-10-30 09:23:09 +00:00
446 lines
12 KiB
Markdown
446 lines
12 KiB
Markdown
kiln(1)
|
|
|
|
# NAME
|
|
|
|
kiln - 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:
|
|
|
|
[[ *Directory*
|
|
:[ *Description*
|
|
| 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.
|
|
|
|
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/.
|
|
|
|
# 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_ configuration file format.
|
|
|
|
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.
|
|
|
|
## 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"
|
|
```
|
|
|
|
## 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,
|
|
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*.
|
|
|
|
## 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
|
|
: Input file extensions
|
|
| output
|
|
: Output file extension
|
|
| template
|
|
: Template file extension
|
|
| preprocess
|
|
: Preprocess commands
|
|
| postprocess
|
|
: Postprocess command
|
|
| static_dir
|
|
: Static content directory
|
|
| output_dir
|
|
: Output directory
|
|
|
|
The input file extension specifies which files from the content directory to
|
|
process. Only files which have the same extension will be processed.
|
|
|
|
The output file extension specifies 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 templates directory. If unset, no templates will be used.
|
|
|
|
The preprocess commands specify commands which will run before content is
|
|
passed to a template. It will be provided the content 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 content is written to the output directory. It will be provided the
|
|
content as standard input and should write the content to standard output.
|
|
|
|
The static content directory controls which directory to use for static content.
|
|
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.
|
|
|
|
The output directory specifies the directory to which the output files will be
|
|
written.
|
|
|
|
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:
|
|
|
|
*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.
|
|
|
|
*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*).
|
|
|
|
*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.
|
|
|
|
## 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
|
|
| Params
|
|
: Extra parameters specified in frontmatter
|
|
|
|
## INDEX TEMPLATES
|
|
|
|
Index templates are provided with all the data that page templates are provided,
|
|
plus the following data:
|
|
|
|
[[ *Variable*
|
|
:[ *Description*
|
|
| Pages
|
|
: List of pages in this directory
|
|
| Dirs
|
|
: List of subdirectories
|
|
|
|
## 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
|
|
|