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`.

## Permalinks

Every page and directory in the site is assigned a path and a permalink.
Paths are relative and point to the source file.
Permalinks are absolute and point to the destination file.

Examples:

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

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

## Templates

Templates are located in the `templates` directory.
There are currently two supported templates:

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

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

### Page templates

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
- `Path`: Relative path to the page
- `Permalink`: Permalink to the page
- `Content`: The contents of the page (excluding the title)

Pages can specify dates in their filenames. kiln will recognize the date and
remove it from the permalink. See [Permalinks](#permalinks) for an example.

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.
```

### Directory index templates

Directory index 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 index 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
```