kiln(1) # NAME kiln - a simple static site generator # SYNOPSIS *kiln* build++ [-c _config_]++ [-t _task_] *kiln* new _path_ *kiln* version # DESCRIPTION *kiln build* builds a kiln site. *kiln new* creates a new kiln site at the given path. *kiln version* prints version information for the *kiln* program. # OPTIONS ## kiln build *-c* _config_ Specifies the configuration file to use. Defaults to "config.toml". *-t* _task_ Specifies the task to run. Defaults to "all", which runs all tasks. # 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/ : Content directory | static/ : Static content directory | templates/ : Template directory | public/ : Output directory Tasks can be configured to use different static content and output directories. The content and template directories are shared between tasks. # 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. ## TASKS Tasks can be specified in the [tasks] table. Each task must have a unique name. The following keys are supported per task: |[ *Key* :[ *Description* | input_ext : Input file extension | output_ext : Output file extension | template_ext : Template file extension | preprocess : Preprocess command | postprocess : Postprocess command | static_dir : Static content directory | output_dir : Output directory The input file extension controls 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 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 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 following configuration generates a Gemini text site and also exports an HTML version of the site. This configuration makes use of the *geminitohtml*(1) command to convert Gemini text to HTML. ``` # Build the site [tasks.gemini] input_ext = ".gmi" output_ext = ".gmi" template_ext = ".gmi" static_dir = "static" output_dir = "public" # Export an HTML version of the site [tasks.geminitohtml] input_ext = ".html" output_ext = ".gmi" template_ext = ".gmi" postprocess = "geminitohtml" static_dir = "static" output_dir = "public.html" ``` The following configuration generates an HTML site from Markdown files in the content directory and HTML templates in the template directory. This configuration makes use of the *markdown*(1) comand to convert Markdown to HTML. ``` [tasks.markdowntohtml] input_ext = ".md" output_ext = ".html" preprocess = "markdown" static_dir = "static" output_dir = "public" ``` ## 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* | page.gmi : Page template | index.gmi : Directory index template | atom.xml : Atom feed 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 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. 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: |[ *Function* :[ *Description* | site : Returns site metadata ## SITE METADATA Site metadata contains the following data: |[ *Variable* :[ *Description* | Title : The title of the site. | URLs : The URLs of the site. To configure these variables, see *CONFIGURATION*. ## PAGE TEMPLATES Page templates are provided with the following data: |[ *Variable* :[ *Description* | Title : The title of the page | Date : The date of the page | Path : 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 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 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.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. ## 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. 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 are provided with the following data: |[ *Variable* :[ *Description* | Title : Title of the feed | Path : Path to the feed directory | Entries : List of pages in this feed The default feed template uses the site URLs, if any, to turn relative links into absolute URLs.