diff --git a/docs/kiln.1.scd b/docs/kiln.1.scd index 8d7a66c..4985c80 100644 --- a/docs/kiln.1.scd +++ b/docs/kiln.1.scd @@ -34,7 +34,7 @@ kiln - a simple static site generator # 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 the content to the output directory. Tasks can also be configured to copy static content to the output directory. @@ -46,10 +46,88 @@ The following directories are common to all tasks: | content/ : Content directory | 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 +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 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 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 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 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 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. 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 written. @@ -135,7 +231,7 @@ command to convert Gemini text to HTML. ``` 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. ``` @@ -148,51 +244,11 @@ configuration makes use of the *markdown*(1) comand to convert Markdown to HTML. output_dir = "public" ``` -## CONTENT DIRECTORY +# TEMPLATES -The content directory contains content that should be processed before -being published. Any file or directory whose name begins with "\_" will be -ignored. +Templates have certain data and functions available to them. -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.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 +## TEMPLATE FUNCTIONS 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 | 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 also specify dates and titles in frontmatter. For example: - - ``` - --- - title: Page title - date: 2021-04-24 - --- - Page content - ``` +| Params +: Extra parameters specified in frontmatter ## 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* :[ *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 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 -Atom feed templates are provided with the following data: +Feed templates are provided with the following data: [[ *Variable* :[ *Description*