mirror of
https://git.sr.ht/~adnano/kiln
synced 2024-10-30 01:13:08 +00:00
docs: Update documentation
This commit is contained in:
adnano
parent
62d414af39
commit
a4a8600c1e
190
docs/kiln.1.scd
190
docs/kiln.1.scd
|
|
@ -29,10 +29,10 @@ kiln - a simple static site generator
|
|||
|
||||
# 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.
|
||||
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:
|
||||
|
||||
|
|
@ -47,23 +47,23 @@ The following directories are common to all tasks:
|
|||
|
||||
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.
|
||||
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.
|
||||
|
||||
; 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.
|
||||
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.
|
||||
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:
|
||||
|
||||
|
|
@ -100,6 +100,8 @@ Templates use the Go templating language. The following templates are supported:
|
|||
: Page template
|
||||
| index.ext
|
||||
: Directory index template
|
||||
| base.ext
|
||||
: Base template from which the page and index templates inherit
|
||||
| atom.xml
|
||||
: Atom feed template
|
||||
|
||||
|
|
@ -111,8 +113,8 @@ 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.
|
||||
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/.
|
||||
|
|
@ -123,7 +125,7 @@ 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 configuration file uses the _TOML_ format.
|
||||
|
||||
The following keys are supported:
|
||||
|
||||
|
|
@ -175,51 +177,116 @@ For more information on templates, see *TEMPLATES*.
|
|||
|
||||
## TASKS
|
||||
|
||||
Tasks can be specified in the [tasks] table. Each task must have a unique name.
|
||||
Tasks can be specified in the [[tasks]] array of tables.
|
||||
|
||||
The following keys are supported per task:
|
||||
The following configuration options 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
|
||||
*input*
|
||||
A list of input file extensions. Files in the content directory with a
|
||||
matching extension will be processed.
|
||||
|
||||
The input file extension specifies which files from the content directory to
|
||||
process. Only files which have the same extension will be processed.
|
||||
Example:
|
||||
|
||||
The output file extension specifies the extension of the file that is written to
|
||||
the output directory.
|
||||
```
|
||||
[[tasks]]
|
||||
input = [".gmi", ".md"]
|
||||
```
|
||||
|
||||
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.
|
||||
*output*
|
||||
The output file extension. Files written to the output directory will use
|
||||
this extension.
|
||||
|
||||
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.
|
||||
Example:
|
||||
|
||||
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.
|
||||
```
|
||||
[[tasks]]
|
||||
output = ".html"
|
||||
```
|
||||
|
||||
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.
|
||||
*template*
|
||||
The template file extension. Templates with this file extension will be used
|
||||
to format the content. If unset, no templates will be used.
|
||||
|
||||
The output directory specifies the directory to which the output files will be
|
||||
written.
|
||||
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)
|
||||
|
|
@ -328,6 +395,16 @@ All templates have the following functions available to them:
|
|||
"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_.
|
||||
|
||||
|
|
@ -477,6 +554,16 @@ All templates have the following functions available to them:
|
|||
|
||||
Site metadata contains the following data:
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"path"
|
||||
)
|
||||
|
||||
func main() {
|
||||
fmt.Println(path.Join("https://example.com", "hello-world"))
|
||||
}
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
| Title
|
||||
|
|
@ -528,3 +615,8 @@ Feed templates are provided with the following data:
|
|||
| Entries
|
||||
: List 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*.
|
||||
|
|
|
|||
Loading…
Reference in a new issue