kiln/README.md
2020-09-29 16:46:54 -04:00

139 lines
2.9 KiB
Markdown

# kiln
A simple static site generator for Gemini.
## Features
- Zero configuration
- Simple and fast
- Gemini support
- Go templates
- Export to HTML
## 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
index.gmi Directory index template
dst/ Site destination
dst.html/ Site HTML destination
```
Running `kiln` takes the contents in `src`, runs them through the templates in
`templates`, and writes the result to `dst`.
If the `-html` flag is provided, `kiln` will also export the Gemini content as
HTML and output it to `dst.html`. The generated HTML will look like this:
```html
<!DOCTYPE html>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link rel="stylesheet" href="/style.css">
<title><!-- Page title --></title>
<!-- Page content -->
```
## Permalinks
Every page and directory in the site is assigned a permalink.
Permalinks are absolute and point to the destination file.
Examples:
```
file: src/posts/2020-09-22-hello-world.gmi
permalink: /posts/hello-world/
directory: src/posts/
permalink: /posts/
```
Pages and directory index files are written to `{{ .Permalink }}/index.html`.
## Templates
Templates are located in the `templates` directory.
There are the supported templates:
- `page.gmi`: The template used for pages
- `index.gmi`: The template used for directory index files
- `atom.xml`: The template used when generating Atom feeds
To generate Atom feeds, run `kiln` with the `-atom` flag.
### 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
- `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:
- `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/index.gmi
{{ range .Pages }}=> {{ .Permalink }}
{{ end }}
$ cat dst/posts/index.gmi
=> /posts/post-1.gmi
=> /posts/post-2.gmi
```