mirror of
https://git.sr.ht/~adnano/kiln
synced 2024-10-30 01:13:08 +00:00
Update documentation
This commit is contained in:
adnano
parent
5be3306c6d
commit
d7f1e11553
198
docs/kiln.1.scd
198
docs/kiln.1.scd
|
|
@ -34,7 +34,7 @@ kiln - a simple static site generator
|
|||
|
||||
# OVERVIEW
|
||||
|
||||
A kiln site is built in one or more steps called _tasks_.
|
||||
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.
|
||||
|
|
@ -46,10 +46,88 @@ The following directories are common to all tasks:
|
|||
| content/
|
||||
: Content directory
|
||||
| templates/
|
||||
: Template directory
|
||||
: 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. For more
|
||||
information on TOML, see https://toml.io/en/v0.4.0.
|
||||
|
||||
|
|
@ -65,6 +143,22 @@ The following keys are supported:
|
|||
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] table. Each task must have a unique name.
|
||||
|
|
@ -95,7 +189,7 @@ 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 template directory. If unset, no templates will be used.
|
||||
be used in the templates directory. If unset, no templates will be used.
|
||||
|
||||
The preprocess command specifies a command which will run before content is
|
||||
passed to a template. It will be provided the content as standard input and
|
||||
|
|
@ -106,7 +200,9 @@ 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.
|
||||
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.
|
||||
|
|
@ -135,7 +231,7 @@ command to convert Gemini text to HTML.
|
|||
```
|
||||
|
||||
The following configuration generates an HTML site from Markdown files in the
|
||||
content directory and HTML templates in the template directory. This
|
||||
content directory and HTML templates in the templates directory. This
|
||||
configuration makes use of the *markdown*(1) comand to convert Markdown to HTML.
|
||||
|
||||
```
|
||||
|
|
@ -148,51 +244,11 @@ configuration makes use of the *markdown*(1) comand to convert Markdown to HTML.
|
|||
output_dir = "public"
|
||||
```
|
||||
|
||||
## CONTENT DIRECTORY
|
||||
# TEMPLATES
|
||||
|
||||
The content directory contains content that should be processed before
|
||||
being published. Any file or directory whose name begins with "\_" will be
|
||||
ignored.
|
||||
Templates have certain data and functions available to them.
|
||||
|
||||
Files in the content directory may be preprocessed, run through templates, and
|
||||
postprocessed (in that order). Each operation takes the output of the last
|
||||
operation as input.
|
||||
|
||||
## STATIC CONTENT DIRECTORY
|
||||
|
||||
All files in the static content directory will be copied to the output
|
||||
directory without modification. Static assets like images should be stored in
|
||||
this directory.
|
||||
|
||||
## TEMPLATE DIRECTORY
|
||||
|
||||
The template 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
|
||||
|
||||
where ".ext" is replaced with the template file extension specified in the
|
||||
task's template_ext configuration option.
|
||||
|
||||
The scope of a template is limited to the directory it is placed in. For
|
||||
example, the template templates/blog/page.gmi will only apply to pages in
|
||||
content/blog.
|
||||
|
||||
Fallback templates can be specified in the templates/\_default directory. These
|
||||
templates will be applied to any directory which does not have its own templates
|
||||
specified.
|
||||
|
||||
For more information on the Go templating language, see
|
||||
https://golang.org/pkg/text/template/.
|
||||
|
||||
## FUNCTIONS
|
||||
## TEMPLATE FUNCTIONS
|
||||
|
||||
All templates have the following functions available to them:
|
||||
|
||||
|
|
@ -228,60 +284,24 @@ Page templates are provided with the following data:
|
|||
: Path to the page
|
||||
| Content
|
||||
: The contents of the page
|
||||
|
||||
Pages can specify dates in their filenames. For example, the file
|
||||
content/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date
|
||||
of November 20, 2020.
|
||||
|
||||
Pages can also specify dates and titles in frontmatter. For example:
|
||||
|
||||
```
|
||||
---
|
||||
title: Page title
|
||||
date: 2021-04-24
|
||||
---
|
||||
Page content
|
||||
```
|
||||
| Params
|
||||
: Extra parameters specified in frontmatter
|
||||
|
||||
## INDEX TEMPLATES
|
||||
|
||||
Index templates are provided with the following data:
|
||||
Index templates are provided with all the data that page templates are provided,
|
||||
plus the following data:
|
||||
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
| Title
|
||||
: Title of the directory
|
||||
| Content
|
||||
: The contents of the directory index file
|
||||
| Path
|
||||
: Path to the directory
|
||||
| Pages
|
||||
: List of pages in this directory
|
||||
| Dirs
|
||||
: List of subdirectories
|
||||
|
||||
The title and content are taken from the index file in the directory. If no
|
||||
index file exists, then the index template will not be rendered.
|
||||
|
||||
## 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"
|
||||
```
|
||||
|
||||
## FEED TEMPLATES
|
||||
|
||||
Atom feed templates are provided with the following data:
|
||||
Feed templates are provided with the following data:
|
||||
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
|
|
|
|||
Loading…
Reference in a new issue