specter/kiln
1
0
Fork 0
mirror of https://git.sr.ht/~adnano/kiln synced 2024-12-28 14:40:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse source
This commit is contained in:
adnano 2021-04-24 14:11:22 -04:00
parent fbf5d3c10d
commit 4710f67ead
1 changed files with 46 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

88
docs/kiln.1.scd
View file

@ -41,7 +41,7 @@ content to the output directory.
The following directories are common to all tasks: The following directories are common to all tasks:
|[ *Directory* [[ *Directory*
:[ *Description* :[ *Description*
| content/ | content/
: Content directory : Content directory
@ -55,7 +55,7 @@ information on TOML, see https://toml.io/en/v0.4.0.
The following keys are supported: The following keys are supported:
|[ *Key* [[ *Key*
:[ *Description* :[ *Description*
| title | title
: Site 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: The following keys are supported per task:
|[ *Key* [[ *Key*
:[ *Description* :[ *Description*
| input_ext | input_ext
: Input file extension : Input file extension
@ -88,31 +88,31 @@ The following keys are supported per task:
| output_dir | output_dir
: Output directory : 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. 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 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 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. 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.
The output directory specifies the directory to write the output files. The output directory specifies the directory to which the output files will be
written.
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 following configuration generates a Gemini text site and also exports an 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. command to convert Gemini text to HTML.
``` ```
@ -125,11 +125,11 @@ command to convert Gemini text to HTML.
output_dir = "public" output_dir = "public"
# Export an HTML version of the site # Export an HTML version of the site
[tasks.geminitohtml] [tasks.exporthtml]
input_ext = ".html" input_ext = ".html"
output_ext = ".gmi" output_ext = ".gmi"
template_ext = ".gmi" template_ext = ".gmi"
postprocess = "geminitohtml" postprocess = "gmnitohtml"
static_dir = "static" static_dir = "static"
output_dir = "public.html" output_dir = "public.html"
``` ```
@ -142,6 +142,7 @@ configuration makes use of the *markdown*(1) comand to convert Markdown to HTML.
[tasks.markdowntohtml] [tasks.markdowntohtml]
input_ext = ".md" input_ext = ".md"
output_ext = ".html" output_ext = ".html"
template_ext = ".html"
preprocess = "markdown" preprocess = "markdown"
static_dir = "static" static_dir = "static"
output_dir = "public" output_dir = "public"
@ -168,22 +169,25 @@ this directory.
The template directory contains templates for use when building the site. The template directory contains templates for use when building the site.
Templates use the Go templating language. The following templates are supported: Templates use the Go templating language. The following templates are supported:
|[ *Template* [[ *Template*
:[ *Description* :[ *Description*
| page.gmi | page.ext
: Page template : Page template
| index.gmi | index.ext
: Directory index template : Directory index template
| atom.xml | atom.xml
: Atom feed template : 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 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 example, the template templates/blog/page.gmi will only apply to pages in
content/blog. content/blog.
kiln has default templates built-in. To override the default templates, put Fallback templates can be specified in the templates/\_default directory. These
templates in the templates/\_default directory. These templates will apply to templates will be applied to any directory which does not have its own templates
any directory which does not have its own templates specified. specified.
For more information on the Go templating language, see For more information on the Go templating language, see
https://golang.org/pkg/text/template/. 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: All templates have the following functions available to them:
|[ *Function* [[ *Function*
:[ *Description* :[ *Description*
| site | site
: Returns site metadata : Returns site metadata
@ -201,7 +205,7 @@ All templates have the following functions available to them:
Site metadata contains the following data: Site metadata contains the following data:
|[ *Variable* [[ *Variable*
:[ *Description* :[ *Description*
| Title | Title
: The title of the site. : The title of the site.
@ -214,7 +218,7 @@ To configure these variables, see *CONFIGURATION*.
Page templates are provided with the following data: Page templates are provided with the following data:
|[ *Variable* [[ *Variable*
:[ *Description* :[ *Description*
| Title | Title
: The title of the page : 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 content/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date
of November 20, 2020. of November 20, 2020.
Pages can specify a title in a top-level heading line. The heading must be the Pages can also specify dates and titles in frontmatter. For example:
first line in the page, and can optionally be followed by a blank line. Both
lines will be removed from the page content. ```
---
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 the following data:
|[ *Variable* [[ *Variable*
:[ *Description* :[ *Description*
| Title | Title
: Title of the directory : Title of the directory
@ -250,17 +260,13 @@ Index templates are provided with the following data:
| Dirs | Dirs
: List of subdirectories : List of subdirectories
The title and content are taken from the index.gmi file in the directory. If no The title and content are taken from the index file in the directory. If no
index.gmi file exists, then the index template will not be rendered. index 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.
## FEEDS ## FEEDS
Feeds can be specified in the [feeds] table of the configuration file. Keys 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 denote the path to the feed directory and values denote the title of the feed.
feed.
Feeds are written to the output directory plus the feed directory plus Feeds are written to the output directory plus the feed directory plus
"atom.xml". "atom.xml".
@ -275,9 +281,9 @@ Example feed configuration:
## FEED TEMPLATES ## FEED TEMPLATES
Feed templates are provided with the following data: Atom feed templates are provided with the following data:
|[ *Variable* [[ *Variable*
:[ *Description* :[ *Description*
| Title | Title
: Title of the feed : Title of the feed
@ -286,5 +292,3 @@ Feed templates are provided with the following data:
| Entries | Entries
: List of pages in this feed : List of pages in this feed
The default feed template uses the site URLs, if any, to turn relative links
into absolute URLs.