2019-05-18 18:00:12 +00:00
|
|
|
# kiln
|
|
|
|
|
|
2020-09-22 20:42:14 +00:00
|
|
|
A simple static site generator for Gemini.
|
2019-05-18 18:00:12 +00:00
|
|
|
|
|
|
|
|
## Features
|
|
|
|
|
|
2020-09-22 20:42:14 +00:00
|
|
|
- Zero configuration
|
2019-05-18 18:00:12 +00:00
|
|
|
- Simple and fast
|
2020-09-22 20:42:14 +00:00
|
|
|
- Gemini support
|
|
|
|
|
- Go templates
|
2020-09-29 18:20:57 +00:00
|
|
|
- Export to HTML
|
2019-05-18 18:00:12 +00:00
|
|
|
|
2020-09-22 20:43:33 +00:00
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
go install
|
|
|
|
|
```
|
|
|
|
|
|
2019-05-18 18:00:12 +00:00
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
kiln
|
|
|
|
|
```
|
|
|
|
|
|
2020-09-22 20:42:14 +00:00
|
|
|
## Directory Structure
|
|
|
|
|
|
|
|
|
|
A kiln site is organized in the following way:
|
|
|
|
|
|
|
|
|
|
```
|
2020-09-23 23:55:11 +00:00
|
|
|
src/ Site source
|
|
|
|
|
templates/ Templates
|
|
|
|
|
page.gmi Page template
|
|
|
|
|
index.gmi Directory index template
|
|
|
|
|
dst/ Site destination
|
2020-09-29 18:20:57 +00:00
|
|
|
dst.html/ Site HTML destination
|
2020-09-22 20:42:14 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Running `kiln` takes the contents in `src`, runs them through the templates in
|
2020-09-23 17:54:40 +00:00
|
|
|
`templates`, and writes the result to `dst`.
|
2020-09-22 20:42:14 +00:00
|
|
|
|
2020-09-29 18:20:57 +00:00
|
|
|
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 -->
|
|
|
|
|
```
|
|
|
|
|
|
2020-09-23 18:03:30 +00:00
|
|
|
## Permalinks
|
|
|
|
|
|
2020-09-29 15:33:17 +00:00
|
|
|
Every page and directory in the site is assigned a permalink.
|
2020-09-23 18:03:30 +00:00
|
|
|
Permalinks are absolute and point to the destination file.
|
|
|
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
file: src/posts/2020-09-22-hello-world.gmi
|
2020-09-29 15:04:25 +00:00
|
|
|
permalink: /posts/hello-world/
|
2020-09-23 18:03:30 +00:00
|
|
|
|
|
|
|
|
directory: src/posts/
|
|
|
|
|
permalink: /posts/
|
|
|
|
|
```
|
|
|
|
|
|
2020-09-29 18:20:57 +00:00
|
|
|
Pages and directory index files are written to `{{ .Permalink }}/index.html`.
|
|
|
|
|
|
2020-09-23 18:03:30 +00:00
|
|
|
## Templates
|
|
|
|
|
|
|
|
|
|
Templates are located in the `templates` directory.
|
|
|
|
|
There are currently two supported templates:
|
|
|
|
|
|
|
|
|
|
- `page.gmi`: The template used for pages
|
2020-09-23 18:12:07 +00:00
|
|
|
- `index.gmi`: The template used for directory index files
|
2020-09-23 18:03:30 +00:00
|
|
|
|
|
|
|
|
If `page.gmi` does not exist, page files will not be created.
|
2020-09-23 18:12:07 +00:00
|
|
|
If `index.gmi` does not exist, directory index files will not be created.
|
2020-09-23 18:03:30 +00:00
|
|
|
|
|
|
|
|
### Page templates
|
2020-09-22 20:42:14 +00:00
|
|
|
|
|
|
|
|
Page templates are provided with the following information:
|
|
|
|
|
|
|
|
|
|
- `Title`: The title parsed from the first heading in the file
|
2020-09-23 18:03:30 +00:00
|
|
|
- `Date`: The date parsed from the filename
|
2020-09-22 20:42:14 +00:00
|
|
|
- `Permalink`: Permalink to the page
|
2020-09-23 18:03:30 +00:00
|
|
|
- `Content`: The contents of the page (excluding the title)
|
2020-09-22 20:42:14 +00:00
|
|
|
|
2020-09-23 17:50:25 +00:00
|
|
|
Pages can specify dates in their filenames. kiln will recognize the date and
|
2020-09-23 18:03:30 +00:00
|
|
|
remove it from the permalink. See [Permalinks](#permalinks) for an example.
|
2020-09-23 17:50:25 +00:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
```
|
|
|
|
|
|
2020-09-23 18:12:07 +00:00
|
|
|
### Directory index templates
|
2020-09-22 20:42:14 +00:00
|
|
|
|
2020-09-23 18:12:07 +00:00
|
|
|
Directory index templates are provided with the following information:
|
2020-09-22 20:42:14 +00:00
|
|
|
|
2020-09-23 01:11:56 +00:00
|
|
|
- `Permalink`: Permalink to the directory
|
|
|
|
|
- `Pages`: The pages in this directory
|
|
|
|
|
- `Directories`: The subdirectories of this directory
|
2020-09-22 20:42:14 +00:00
|
|
|
|
2020-09-23 18:12:07 +00:00
|
|
|
Directory index templates are written to `index.gmi` in the corresponding directory.
|
2020-09-23 18:03:30 +00:00
|
|
|
|
2020-09-23 17:50:25 +00:00
|
|
|
Example:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
$ ls src/posts/
|
|
|
|
|
src/posts/post-1.gmi
|
|
|
|
|
src/posts/post-2.gmi
|
|
|
|
|
|
2020-09-29 15:34:03 +00:00
|
|
|
$ cat templates/index.gmi
|
2020-09-29 16:48:50 +00:00
|
|
|
{{ range .Pages }}=> {{ .Permalink }}
|
2020-09-23 17:50:25 +00:00
|
|
|
{{ end }}
|
|
|
|
|
|
|
|
|
|
$ cat dst/posts/index.gmi
|
|
|
|
|
=> /posts/post-1.gmi
|
|
|
|
|
=> /posts/post-2.gmi
|
|
|
|
|
```
|
