kiln

A custom static site generator (SSG) written in Rust, replacing a Hugo + LoveIt stack for hakula.xyz.

Overview

kiln is purpose-built for hakula.xyz: strong CJK-friendly authoring, explicit rendering behavior, and a theme system that stays understandable. Instead of chasing broad SSG feature parity, it focuses on a smaller publishing workflow that is easier to reason about and extend.

Highlights

Authoring

• TOML frontmatter, GitHub Flavored Markdown, KaTeX math
• CJK-friendly heading IDs and table of contents generation
• ::: directives with theme-template rendering
• Directive template helpers (read_file, parse_csv)
• Mermaid diagrams via ```mermaid fences
• Syntax highlighting for 200+ languages, image attributes, emoji and Font Awesome icon shortcodes

Site Generation

• Pretty URLs, static file copying, co-located content assets, per-page CSS bundling
• Home pages, section pages, standalone pages, taxonomy indexes, and paginated term pages
• Pinned posts on the home page via weight frontmatter
• Page-scoped asset registry — themes load KaTeX / Mermaid / search only on pages that need them
• Configurable site time zone for rendered dates
• Build-time image pipeline — every <img> gets natural width/height plus a base64 WebP LQIP backdrop, so the browser reserves the exact box and paints a low-frequency placeholder while the source decodes
• RSS feeds, sitemap, custom 404 page
• Full-text search via Pagefind

Internationalization

• Translatable theme strings with layered TOML overrides — themes ship defaults, sites customize freely
• Localized templates and navigation menus, with graceful fallback to English when a translation is missing

Theming

• MiniJinja templates with layered site overrides and theme parameter merging
• Ships with IgnIt: Tailwind CSS v4, glassmorphism panels with optional cursor-tracking glow, dark mode, responsive layout, search modal, back-to-top, mobile menu animations, print styles, keyboard accessibility

Tooling

• Dev server with live reload (kiln serve)
• Hugo-to-kiln content migration (kiln convert)
• Theme scaffolding (kiln init-theme)
• Optional HTML / CSS / JS minification (kiln build --minify)

Documentation

Document	Description
Roadmap	Current shipped capability areas and planned work
Content Guide	Page bundles, co-located assets, per-page CSS
Syntax Guide	Markdown extensions, frontmatter fields, directives
Theming	Themes, templates, navigation menus, and i18n

Current Focus

Ongoing engine and theme polish driven by real publishing needs. See the roadmap for details.

Installation

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

From source

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

Via Nix

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

Or as a flake input from another project (e.g., a site repo):

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

pagefind ships alongside kiln so consumers don't have to pin the search backend separately.

See RELEASING.md for how releases are produced.

Usage

kiln build                                                # Build the site
kiln build --root /path/to/site                           # Build from a specific root
kiln build --minify                                       # Build, then minify HTML / CSS / JS
kiln serve                                                # Dev server with live reload
kiln serve --port 3000 --open                             # Custom port, auto-open browser
kiln init-theme my-theme                                  # Scaffold a new theme
kiln convert --source /path/to/hugo --dest /path/to/kiln  # Convert a Hugo site

Minification

Passing --minify to kiln build runs a Rust-native pass over the output directory and rewrites each HTML / CSS / JS file in place:

• HTML via minify-html
• CSS via lightningcss
• JS via oxc_minifier

Files matching *.min.css or *.min.js are skipped so that pre-minified vendor bundles (e.g., Pagefind's UI JS) pass through untouched. Unusable inputs log a warning and keep the original file, so --minify never blocks a build.

Search

kiln integrates with Pagefind for full-text search. Install the binary (cargo install pagefind or npm install -g pagefind), then enable it in config.toml:

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

kiln build and kiln serve both run Pagefind automatically after HTML generation.

Building from Source

Requires Rust 1.85+ (edition 2024) and libdav1d (for the image crate's AVIF decoder).

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

Reproducible dev shell (Nix)

For hacking on kiln itself, the shipped flake.nix pins the Rust toolchain, libdav1d, pagefind, git-cliff, and pre-commit hooks:

nix develop      # interactive shell
nix flake check  # run pre-commit hooks

direnv auto-activates the shell via .envrc.

License

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