kiln

A static site generator written in Rust for hakula.xyz, with CJK-friendly Markdown authoring and customizable themes.

Highlights

• CJK-friendly Markdown for technical writing, with math, diagrams and syntax highlighting
• Custom content components through nested ::: directives and theme templates
• Page bundles that keep writing, images and page-specific styles together
• Full-text search via Pagefind, with archives and feeds for finding and following posts
• IgnIt theme with responsive layouts and dark mode, customizable through site overrides
• Local preview with live reload, plus optimized stylesheets and image loading placeholders for publication

Documentation

Installation

Via npm

Install Node.js 20 or newer, for example with fnm, then choose one kiln variant:

fnm install --latest --use
npm install -g @kiln-ssg/kiln@latest

Choose @kiln-ssg/kiln-extended@latest for AVIF loading placeholders. It has the same dav1d requirements as the extended archive. Both variants install kiln, so uninstall the current variant before switching.

Prereleases use the next npm tag. Supported platforms are Linux x86_64 (glibc), Apple Silicon and Windows x86_64.

Add optional tools to the same installation command when your site needs them:

npm install -g @kiln-ssg/kiln@latest @kiln-ssg/[email protected] [email protected]

• @kiln-ssg/tailwindcss: required when the site or theme compiles Tailwind CSS.
• pagefind: required when search is enabled.

Prebuilt binary

Download the latest release for your platform from Releases:

# Linux x86_64
curl -fsSL https://github.com/hakula139/kiln/releases/latest/download/kiln-x86_64-unknown-linux-gnu.tar.gz | tar -xz
sudo mv kiln /usr/local/bin/

# macOS aarch64 (Apple Silicon)
curl -fsSL https://github.com/hakula139/kiln/releases/latest/download/kiln-aarch64-apple-darwin.tar.gz | tar -xz
sudo mv kiln /usr/local/bin/

# Windows x86_64 (Git Bash / MSYS / WSL)
curl -fsSLO https://github.com/hakula139/kiln/releases/latest/download/kiln-x86_64-pc-windows-msvc.zip
unzip kiln-x86_64-pc-windows-msvc.zip

kiln --version

Choose the default kiln-<target> archive or kiln-extended-<target> for AVIF loading placeholders. Only extended binaries need dav1d:

From source

cargo install --git https://github.com/hakula139/kiln --locked

To generate loading placeholders for AVIF images, install the native dependencies and enable the feature:

cargo install --git https://github.com/hakula139/kiln --locked --features avif

Via Nix

nix run github:hakula139/kiln -- build     # one-shot
nix profile install github:hakula139/kiln  # install to user profile

The flake offers the hakula Cachix cache for prebuilt packages. Nix prompts for trust interactively. For noninteractive use, verify the cache key before passing --accept-flake-config.

To use this cache from another flake, configure it in that flake or your Nix installation.

To use kiln in another flake, add this input:

inputs.kiln.url = "github:hakula139/kiln";
# Outputs: packages.${system}.{default,kiln}

The Nix package puts the Tailwind compiler and Pagefind on kiln's PATH, so stylesheet compilation and search work without separate installs.

First Site

Create a site with IgnIt, using a kiln version meeting the theme's min_kiln_version. IgnIt requires the Tailwind processor, which is included in kiln's Nix package.

git init my-site
cd my-site
git submodule add https://github.com/hakula139/IgnIt.git themes/IgnIt
mkdir -p content/posts/hello

cat > config.toml <<'CONFIG'
base_url = "https://example.com"
title = "My Site"
theme = "IgnIt"
CONFIG

cat > content/posts/hello/index.md <<'POST'
+++
title = "Hello"
+++

Welcome to my site.
POST

kiln serve --open

Run kiln build --minify to generate public/ for deployment. See Site Configuration for engine settings and Content for organizing pages.

Usage

kiln build --root /path/to/site --minify
kiln build --base-url https://preview.example.com
kiln serve --port 3000 --open
kiln init-theme my-theme
kiln convert --source /path/to/hugo --dest /path/to/kiln

build, serve and init-theme use the current directory as the site root unless --root is supplied. KILN_BASE_URL supplies a build URL override when --base-url is absent.

See Hugo migration for the converter's supported scope and manual follow-up.

Search

Search is disabled by default. To enable it, install Pagefind and set [search] enabled = true in config.toml:

[search]
enabled = true
# binary = "/path/to/pagefind"  # optional, if not on $PATH

kiln build and kiln serve run Pagefind after HTML generation when search is enabled.

Building from Source

Requires Rust 1.89 or newer and a C toolchain.

cargo build --release  # Binary at target/release/kiln

AVIF placeholders

Image publication and dimension detection work in either build. To add AVIF loading placeholders, install dav1d ≥ 1.3 and pkg-config:

Then enable the feature:

cargo build --release --features avif

On macOS and Linux, the resulting binary needs dav1d at runtime, like the extended archives.

Reproducible dev shell (Nix)

The Nix package enables AVIF support by default. Its development shell provides the build dependencies and pre-commit hooks:

nix develop      # interactive shell
nix flake check  # run the pre-commit hooks that don't use Node

direnv auto-activates the shell via .envrc.

License

Copyright (c) 2026 Hakula. Licensed under the MIT License.