kiln tutorial

Site creation

Now that we have kiln installed, we can use it to build sites. We'll start off by creating a new site.

Run 'kiln new <path>' to create a new Gemini site at the given path.

# This command creates a Gemini site named 'exampleSite'
kiln new exampleSite

Note: kiln can be used to build sites with any kind of content, including Gemini text, Markdown, HTML, or a combination of multiple content types. However, the 'kiln new' command only creates Gemini sites. You can modify the default configuration to build sites with other content types.

The generated site will have the provided structure:

├── config.toml
├── content
│   └── index.gmi
├── public
├── static
└── templates
    └── _default
        ├── atom.xml
        ├── index.gmi
        └── page.gmi

5 directories, 5 files

The 'content' directory contains site content. In this case, it contains Gemini text files.

The 'templates' directory contains templates that will be used to assemble the site. The default templates include index.gmi (used to render index.gmi files), page.gmi (used to render Gemini text files), and atom.xml (used to render Atom feeds). These templates are all optional and kiln can be used without them.

The 'static' directory contains static files that will be copied unmodified to the output directory.

The 'public' directory is the site output directory and will contain the final built site.

The site configuration is stored in config.toml. Be sure to look over the default configuration and modify it to suit your needs.

To build the site, run 'kiln build'. This command will read content from the content directory, process it, run it through templates, and write the result to the output directory ('public' by default).

# Build the site
kiln build

After building, the site files should be published to the 'public' directory.

Create a post

Now you can create your first post. Open the file 'content/my-first-post.gmi' in your favorite $EDITOR:

$ $EDITOR content/my-first-post.gmi
$ cat content/my-first-post.gmi
title: My first post
date: 2021-06-25

This is my first post!

We can use frontmatter to store extra information about our post. In this case, we used it to specify the title and date of the post.

Build the site again. You should see your post appear on the homepage.