kiln/README.md

# kiln

A simple static site generator for Gemini.

## Features

- Zero configuration
- Simple and fast
- Gemini support
- Go templates

## Installation

```
go install
```

## Usage

```
kiln
```

## Directory Structure

A kiln site is organized in the following way:

```
src/               Site source
templates/         Templates
    page.gmi       Page template
    directory.gmi  Directory template
dst/               Site destination
```

Running `kiln` takes the contents in `src`, runs them through the templates in
`templates`, and writes the result to `dst`.

## Pages

Page templates are provided with the following information:

- `Title`: The title parsed from the first heading in the file
- `Date`: The date parsed from the filename (e.g. `2020-09-22-hello-world.gmi`)
- `Path`: Relative path to the page
- `Permalink`: Permalink to the page
- `Content`: The contents of the file (including the title)

Pages can specify dates in their filenames. kiln will recognize the date and
remove it from the permalink.

Pages can also specify titles in their content. kiln will parse and remove the
title from the content. Example:

```
$ cat src/hello-world.gmi
# Hello, world!

This is some content.

$ cat templates/page.gmi
Title: {{ .Title }}
Content:
{{ .Content }}

$ cat dst/hello-world.gmi
Title: Hello, world!
Content:
This is some content.
```

## Directories

Directory templates are provided with the following information:

- `Path`: Relative path to the directory
- `Permalink`: Permalink to the directory
- `Pages`: The pages in this directory
- `Directories`: The subdirectories of this directory

Directory templates are written to `index.gmi` in the corresponding directory.
Example:

```
$ ls src/posts/
src/posts/post-1.gmi
src/posts/post-2.gmi

$ cat templates/directory.gmi
{{ range .Pages }}=> .Permalink
{{ end }}

$ cat dst/posts/index.gmi
=> /posts/post-1.gmi
=> /posts/post-2.gmi
```

## Templates

Templates are located in the `templates` directory.

There are currently two supported templates:

- `page.gmi`: The template used for pages
- `directory.gmi`: The template used for directories

If `page.gmi` does not exist, page files will not be created.
If `directory.gmi` does not exist, directory index files will not be created.

## Permalinks

Every page and directory in the site is assigned a path and a permalink.

```
file:      src/posts/2020-09-22-hello-world.gmi
path:      posts/2020-09-22-hello-world.gmi
permalink: /posts/hello-world.gmi
```

Paths are relative and point to the source file.
Permalinks are absolute and point to the destination file.

Here is an example of a directory:

```
directory: src/posts/
path:      posts
permalink: /posts/
```