mirror/kiln
1
0
Fork 0
mirror of https://git.sr.ht/~adnano/kiln synced 2024-11-08 14:19:20 +01:00
Code Issues Activity

Update documentation

Browse Source
This commit is contained in:
adnano 2021-04-12 00:23:27 -04:00
parent 02ca7d1549
commit 68ae146361
1 changed files with 90 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

168
doc/kiln.1.scd
View File

@ -2,39 +2,80 @@ kiln(1)
# NAME
kiln - a simple static site generator for Gemini sites
kiln - a simple static site generator
# SYNOPSIS
_kiln_ [--html]
_kiln_ [-c <config>] [-t <task>]
# OPTIONS
\--format <format>
Specifies the output format to use. Supported formats include gemini and html. Defaults to "gemini".
\-c <config>
Specifies the configuration file to use. Defaults to "config.toml".
# SITE STRUCTURE
\-t <task>
Specifies the task to run. Defaults to "all", which runs all tasks.
A kiln site is structured in the following way:
# OVERVIEW
A kiln site is built in one or more steps called _tasks_.
There is only one default task called "gemini" which builds a Gemini site.
The following directories are used by default:
[[ *Directory*
:[ *Description*
| content/
: Site source
: Content directory
| static/
: Static content directory
| templates/
: Site templates
: Template directory
| public/
: Site destination
: Output directory
All files in the source directory will be copied to the destination directory.
If the file is a Gemini file, it will be passed through a template and the result will be written to the destination directory.
Any file or directory whose name begins with "\_" will be ignored.
Tasks can be configured to use different static content and output directories.
The content and template directories are shared between tasks.
# TEMPLATES
kiln looks for templates in the *templates* directory.
Templates use the Go templating language.
The following templates are supported:
# CONFIGURATION
The configuration file uses the _TOML_ configuration file format. For more
information on TOML, see https://toml.io/en/v0.4.0.
The following keys are supported:
[[ *Key*
:[ *Description*
| title
: Site title
| urls
: A list of site URLs
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.
## CONTENT DIRECTORY
The content directory contains content that should be processed before
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
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*
@ -44,13 +85,17 @@ The following templates are supported:
: Directory index template
| atom.xml
: Atom feed template
| output.html
: HTML output template
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 src/blog.
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.
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.
For more information on the Go templating language, see
https://golang.org/pkg/text/template/.
## FUNCTIONS
@ -63,7 +108,7 @@ All templates have the following functions available to them:
## SITE METADATA
Site metadata contains the following information:
Site metadata contains the following data:
[[ *Variable*
:[ *Description*
@ -76,7 +121,7 @@ To configure these variables, see *CONFIGURATION*.
## PAGE TEMPLATES
Page templates are provided with the following information:
Page templates are provided with the following data:
[[ *Variable*
:[ *Description*
@ -89,16 +134,17 @@ Page templates are provided with the following information:
| Content
: The contents of the page
Pages can specify dates in their filenames.
For example, src/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date of November 20, 2020.
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 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.
## INDEX TEMPLATES
Index templates are provided with the following information:
Index templates are provided with the following data:
[[ *Variable*
:[ *Description*
@ -113,14 +159,23 @@ Index templates are provided with the following information:
| 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 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 default index template implements the lightweight subscription specification
found at gemini://gemini.circumlunar.space/docs/companion/subscription.gmi.
## FEEDS
Feeds can optionally 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.
Feeds are written to the directory path plus "atom.xml".
## FEED TEMPLATES
Atom feed templates are provided with the following information:
Feed templates are provided with the following data:
[[ *Variable*
:[ *Description*
@ -131,48 +186,5 @@ Atom feed templates are provided with the following information:
| Entries
: List of pages in this feed
Feeds are written to the directory path plus "atom.xml".
The default feed template uses the site URLs, if present, to make relative links into absolute URLs.
## HTML TEMPLATES
HTML output templates are provided with the following information:
[[ *Variable*
:[ *Description*
| Title
: Title of the page
| Content
: HTML contents of the page
# CONFIGURATION
kiln looks for a configuration file named "config.ini".
The configuration file uses the _ini_ format.
A line beginning with ";" is considered a comment and ignored, as are empty lines.
New sections begin with [section-name] on a single line.
Keys and values are separated with "=".
The following keys are supported:
[[ *Key*
:[ *Description*
| title
: Site title
| url
: One or more site URLs separated by whitespace.
Site URLs are used when generating Atom feeds.
Site URLs may contain paths, but should not end with a trailing slash.
Multiple site URLs may be specified if they are separated by whitespace.
This allows a site that is hosted on both Gemini and HTTP to specify URLs for both locations.
The following sections are supported:
[[ *Section*
:[ *Description*
| feeds
: A list of Atom feeds. Keys denote the path to the feed directory, and values denote the title of the feed.
The default feed template uses the site URLs, if any, to turn relative links
into absolute URLs.