specter/kiln
1
0
Fork 0
mirror of https://git.sr.ht/~adnano/kiln synced 2024-10-30 01:13:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse source
This commit is contained in:
adnano 2021-04-26 14:49:39 -04:00
parent 5be3306c6d
commit d7f1e11553
1 changed files with 109 additions and 89 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

198
docs/kiln.1.scd
View file

@ -34,7 +34,7 @@ kiln - a simple static site generator
# OVERVIEW # 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 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 the content to the output directory. Tasks can also be configured to copy static
content to the output directory. content to the output directory.
@ -46,10 +46,88 @@ The following directories are common to all tasks:
| content/ | content/
: Content directory : Content directory
| templates/ | 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 # 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 The configuration file uses the _TOML_ configuration file format. For more
information on TOML, see https://toml.io/en/v0.4.0. 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 contain paths, but should not end with a trailing slash. Multiple
site URLs may be specified for sites that are available at multiple locations. 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
Tasks can be specified in the [tasks] table. Each task must have a unique name. 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 output directory.
The template file extension specifies the extension of the templates that will 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 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 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. content as standard input and should write the content to standard output.
The static content directory controls which directory to use for static content. 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 The output directory specifies the directory to which the output files will be
written. written.
@ -135,7 +231,7 @@ command to convert Gemini text to HTML.
``` ```
The following configuration generates an HTML site from Markdown files in the 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. 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" output_dir = "public"
``` ```
## CONTENT DIRECTORY # TEMPLATES
The content directory contains content that should be processed before Templates have certain data and functions available to them.
being published. Any file or directory whose name begins with "\_" will be
ignored.
Files in the content directory may be preprocessed, run through templates, and ## TEMPLATE FUNCTIONS
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
All templates have the following functions available to them: 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 : Path to the page
| Content | Content
: The contents of the page : The contents of the page
| Params
Pages can specify dates in their filenames. For example, the file : Extra parameters specified in frontmatter
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
```
## INDEX TEMPLATES ## 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* [[ *Variable*
:[ *Description* :[ *Description*
| Title
: Title of the directory
| Content
: The contents of the directory index file
| Path
: Path to the directory
| Pages | Pages
: List of pages in this directory : List of pages in this directory
| Dirs | Dirs
: List of subdirectories : 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 ## FEED TEMPLATES
Atom feed templates are provided with the following data: Feed templates are provided with the following data:
[[ *Variable* [[ *Variable*
:[ *Description* :[ *Description*