mirror of
https://git.sr.ht/~adnano/kiln
synced 2024-11-08 10:09:18 +01:00
Update documentation
This commit is contained in:
adnano
parent
fbf5d3c10d
commit
4710f67ead
@ -41,7 +41,7 @@ content to the output directory.
|
||||
|
||||
The following directories are common to all tasks:
|
||||
|
||||
|[ *Directory*
|
||||
[[ *Directory*
|
||||
:[ *Description*
|
||||
| content/
|
||||
: Content directory
|
||||
@ -55,7 +55,7 @@ information on TOML, see https://toml.io/en/v0.4.0.
|
||||
|
||||
The following keys are supported:
|
||||
|
||||
|[ *Key*
|
||||
[[ *Key*
|
||||
:[ *Description*
|
||||
| title
|
||||
: Site title
|
||||
@ -71,7 +71,7 @@ Tasks can be specified in the [tasks] table. Each task must have a unique name.
|
||||
|
||||
The following keys are supported per task:
|
||||
|
||||
|[ *Key*
|
||||
[[ *Key*
|
||||
:[ *Description*
|
||||
| input_ext
|
||||
: Input file extension
|
||||
@ -88,31 +88,31 @@ The following keys are supported per task:
|
||||
| output_dir
|
||||
: Output directory
|
||||
|
||||
The input file extension controls which files from the content directory to
|
||||
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 controls the extension of the file that is written to
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
The output directory specifies the directory to write the output files.
|
||||
|
||||
The preprocess command specifies a command which will run before the content is
|
||||
passed to the template. It will be provided the content of the file 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 the content is written to the output directory. It will be provided
|
||||
the content of the file as standard input and should write the processed content
|
||||
to standard output.
|
||||
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 *geminitohtml*(1)
|
||||
HTML version of the site. This configuration makes use of the *gmnitohtml*(1)
|
||||
command to convert Gemini text to HTML.
|
||||
|
||||
```
|
||||
@ -125,11 +125,11 @@ command to convert Gemini text to HTML.
|
||||
output_dir = "public"
|
||||
|
||||
# Export an HTML version of the site
|
||||
[tasks.geminitohtml]
|
||||
[tasks.exporthtml]
|
||||
input_ext = ".html"
|
||||
output_ext = ".gmi"
|
||||
template_ext = ".gmi"
|
||||
postprocess = "geminitohtml"
|
||||
postprocess = "gmnitohtml"
|
||||
static_dir = "static"
|
||||
output_dir = "public.html"
|
||||
```
|
||||
@ -142,6 +142,7 @@ configuration makes use of the *markdown*(1) comand to convert Markdown to HTML.
|
||||
[tasks.markdowntohtml]
|
||||
input_ext = ".md"
|
||||
output_ext = ".html"
|
||||
template_ext = ".html"
|
||||
preprocess = "markdown"
|
||||
static_dir = "static"
|
||||
output_dir = "public"
|
||||
@ -168,22 +169,25 @@ this directory.
|
||||
The template directory contains templates for use when building the site.
|
||||
Templates use the Go templating language. The following templates are supported:
|
||||
|
||||
|[ *Template*
|
||||
[[ *Template*
|
||||
:[ *Description*
|
||||
| page.gmi
|
||||
| page.ext
|
||||
: Page template
|
||||
| index.gmi
|
||||
| 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.
|
||||
|
||||
kiln has default templates built-in. To override the default templates, put
|
||||
templates in the templates/\_default directory. These templates will apply to
|
||||
any directory which does not have its own templates specified.
|
||||
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/.
|
||||
@ -192,7 +196,7 @@ https://golang.org/pkg/text/template/.
|
||||
|
||||
All templates have the following functions available to them:
|
||||
|
||||
|[ *Function*
|
||||
[[ *Function*
|
||||
:[ *Description*
|
||||
| site
|
||||
: Returns site metadata
|
||||
@ -201,7 +205,7 @@ All templates have the following functions available to them:
|
||||
|
||||
Site metadata contains the following data:
|
||||
|
||||
|[ *Variable*
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
| Title
|
||||
: The title of the site.
|
||||
@ -214,7 +218,7 @@ To configure these variables, see *CONFIGURATION*.
|
||||
|
||||
Page templates are provided with the following data:
|
||||
|
||||
|[ *Variable*
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
| Title
|
||||
: The title of the page
|
||||
@ -229,15 +233,21 @@ 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 specify a title in a top-level heading line. The heading must be the
|
||||
first line in the page, and can optionally be followed by a blank line. Both
|
||||
lines will be removed from the page content.
|
||||
Pages can also specify dates and titles in frontmatter. For example:
|
||||
|
||||
```
|
||||
---
|
||||
title: Page title
|
||||
date: 2021-04-24
|
||||
---
|
||||
Page content
|
||||
```
|
||||
|
||||
## INDEX TEMPLATES
|
||||
|
||||
Index templates are provided with the following data:
|
||||
|
||||
|[ *Variable*
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
| Title
|
||||
: Title of the directory
|
||||
@ -250,17 +260,13 @@ Index templates are provided with the following data:
|
||||
| Dirs
|
||||
: List of subdirectories
|
||||
|
||||
The title and content are taken from the index.gmi file in the directory. If no
|
||||
index.gmi file exists, then the index template will not be rendered.
|
||||
|
||||
The default index template implements the lightweight subscription specification
|
||||
found at gemini://gemini.circumlunar.space/docs/companion/subscription.gmi.
|
||||
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 input directory and values denote the title of the
|
||||
feed.
|
||||
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".
|
||||
@ -275,9 +281,9 @@ Example feed configuration:
|
||||
|
||||
## FEED TEMPLATES
|
||||
|
||||
Feed templates are provided with the following data:
|
||||
Atom feed templates are provided with the following data:
|
||||
|
||||
|[ *Variable*
|
||||
[[ *Variable*
|
||||
:[ *Description*
|
||||
| Title
|
||||
: Title of the feed
|
||||
@ -286,5 +292,3 @@ Feed templates are provided with the following data:
|
||||
| Entries
|
||||
: List of pages in this feed
|
||||
|
||||
The default feed template uses the site URLs, if any, to turn relative links
|
||||
into absolute URLs.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user