Kiln example site

Search Tips

2026-07-25T00:00:00.000Z

The search box in the site header is client-side: Kiln builds a JSON index of every published page at dist/search-index.json, ships a tiny script alongside it, and the browser does the filtering. No server, no service, no tracking.

How the index is built

Each entry carries a title, the page URL, a plain-text excerpt, and the post's tags. Because the index is generated after the publish filter, drafts and future posts are absent from it — you cannot find what was never shipped.

Getting good results

Search for whole words: frontmatter, sitemap, highlighting.
Tags are part of the index, so showcase surfaces the showcase posts.
Results update as you type; the empty state tells you when nothing matched.

What it will not do

The demo script has no fuzzy matching and no stemming — it favors predictability over cleverness. For a site of this size, that is plenty.

Feeds and Sitemaps

2026-06-18T00:00:00.000Z

Two machine-readable outputs ship with every build: an Atom feed at /feed.xml and a sitemap at /sitemap.xml. Both are generated from the published posts, so a draft or a future-dated post can never leak into either.

The Atom feed

The feed lists the newest posts — capped by features.feed.limit, which this site sets to 10 — with absolute URLs derived from site.url. Every page also advertises it from the document head:

<link rel="alternate" type="application/atom+xml" href="/feed.xml">

Point a reader at the feed URL, or let them discover it automatically; both work because the link tag is in the template, not hand-written per page.

The sitemap

sitemap.xml enumerates every emitted URL: the home list and its overflow pages, each post, each static page, and every tag archive. The crawler that reads it maps each <loc> straight back to a file inside dist/.

Why absolute URLs matter

Feeds and sitemaps are consumed off-site, so relative URLs are meaningless there. Kiln rejects a build whose site.url is not an absolute http(s) origin — the example site sets https://example.com in kiln.config.ts.

Syntax Highlighting Tour

2026-05-12T00:00:00.000Z

A long-form tour of Kiln's build-time syntax highlighting. Everything on this page was highlighted while the site was built — there is no client-side highlighting library, just spans baked into the HTML. The tour doubles as the demo page for the table of contents above the article and for the related-posts list at the bottom.

Why highlight at build time?

Shipping a highlighting library to the browser means every visitor pays for it: more JavaScript, more CSS, and a flash of unstyled code before the library runs. Kiln resolves the fence's language at build time and emits <span class="hljs-…"> token markup once, so readers get colored code from the first byte.

The trade-off is honest: highlighting is frozen at build time, and changing the theme means rebuilding the site. For documentation and blogs that is exactly the right trade.

TypeScript fences

The info string's first word picks the language. A ts fence becomes a labelled, highlighted block:

/** One build report line — what the CLI prints after emit. */
export interface EmittedPage {
  url: string;
  file: string;
}

export function summarize(pages: EmittedPage[]): string {
  const total = pages.length;
  const newest = pages.at(-1)?.url ?? "(none)";
  return `${total} pages, newest ${newest}`;
}

Unknown languages fall back to an escaped plain block, so a fence is never blank and never crashes the render.

CSS fences

Stylesheets get the same treatment:

:root {
  --accent: #0969da;
}

.post-card h2 a {
  color: var(--text);
  text-decoration: none;
}

.post-card h2 a:hover {
  color: var(--accent);
}

Token markup under the hood

Highlighted output is plain HTML with hljs- prefixed spans — the theme in dist/assets/hljs.css styles the classes, and nothing else needs to run. Grep the built page for hljs- and you will find dozens of hits.

What gets a label

Any recognized language renders a small label above the block, taken from the fence's info string.

What falls back

A fence with no info string, or one naming a language Kiln does not know, renders as escaped monospace text — still readable, just not colored.

Themes

The example site picks github-dark in kiln.config.ts. Swapping the key to any bundled highlight.js style changes the emitted stylesheet without touching a single template.

Where this shows up elsewhere

Highlighted code appears across the example content — the build snippet in Hello, Kiln, the shell sessions in Writing Markdown, and the YAML block in Frontmatter Fields — so the tour is also a reminder that good examples should be runnable.

Café Münster 日本語

2026-03-30T00:00:00.000Z

This post exists to prove that Kiln handles Unicode everywhere it counts: the filename café-münster-日本語.md becomes the URL /posts/café-münster-日本語/, the title keeps its accents and its Japanese script, and the slug stays readable in both.

A trip through three scripts

We started in Café Münster — flat whites and filter coffee — before the rails carried us east. Somewhere between the second interchange and the last stop, the announcements switched to 日本語, and the platform signs began to blur together in the best possible way.

What the pipeline does with it

The filename is NFC-normalized and lowercased; letters from any script survive into the slug, punctuation is dropped.
Emitted paths are percent-encoded only where HTTP requires it — the file on disk keeps its real name.

Unicode is not an edge case. Half the web's authors write in scripts that are not ASCII, and a generator that mangles their filenames is simply broken.

Template Layouts

2026-02-14T00:00:00.000Z

Layouts are HTML templates with a few template-language tags. The example site ships three of them — base.html, index.html, and post.html — plus a partials/ folder for reusable fragments.

How a document picks a layout

A document renders through the template its frontmatter names, falling back to the post layout when none is set. index.html declares its own:

---
layout: index
---

In the template itself, the chain is ordinary template inheritance:

{% extends "base.html" %}
{% block content %}
<h1>{{ page.title }}</h1>
{{ content | safe }}
{% endblock %}

base.html owns the document head — the Atom feed link, the stylesheets, the navigation and search box — while every other layout fills the content block.

Partials

Small fragments live in templates/partials/ and are pulled in by bare name. The navigation embeds the search widget with a single include, and the table of contents on this very page comes from a partial too.

Strict by default

A typo like {{ titel }} fails the build with the template name and line number instead of shipping an empty heading.

Frontmatter Fields

2026-01-20T00:00:00.000Z

Frontmatter is the YAML block between --- fences at the top of a Markdown file. It is where a document declares the metadata that the rest of the pipeline consumes — and every feature reads only the fields it owns.

The fields this site uses

---
title: Frontmatter Fields   # shown in <title>, lists, and the feed
date: 2026-01-20            # ordering, archives, scheduling
tags: [reference]           # tag archives and related-post scoring
draft: true                 # hides a post unless --drafts is passed
layout: index               # which template renders the document
---

What happens to it

The parser validates that the block is a YAML mapping and that date is a real date; anything else is left alone for features to check.
tags must be a list of non-empty strings — an empty tag fails the build with a message naming the file.
layout chooses the template; when it is absent, posts render through the default post layout.

Defaults you rarely touch

Directory names (content/, templates/, public/, dist/) live in kiln.config.ts and stay at their defaults here, so the whole site resolves relative to its own folder.

Writing Markdown

2025-12-15T00:00:00.000Z

Markdown is the input format for every page on this site. This post walks through the constructs the example content actually uses — headings, lists, tables, strikethrough, and fenced code — so you can see how each one renders before you write your own pages.

Tables, strikethrough, and friends

Kiln's renderer understands GitHub-flavored Markdown. You can ~~cross out old ideas~~ while keeping them readable in the source, and lay data out in a table:

Construct	Syntax	Renders as
Bold	`text`	text
Strikethrough	`~~text~~`	~~text~~
Code span	`code`	`code`

Shell sessions in fences

Bash commands belong in a fenced block with the bash info string, which the highlighter picks up:

cd site && node ../src/cli.ts build   # bake the example site
cd site && node ../src/cli.ts serve   # browse it locally

A checklist for new posts

Give every post a distinct, past date.
Tag it so it lands in a tag archive.
Open with a prose paragraph — it becomes the home-page excerpt.

Hello, Kiln

2025-11-02T00:00:00.000Z

Kiln turns a folder of Markdown into a static website. This post is the first of the example content: it carries a TypeScript code sample, links to the little image asset the site ships with, and shows up on the home list with an excerpt, a date, and a reading time.

Why a static site?

Static output is easy to host, cheap to scale, and has no database to break at 3 a.m. You write Markdown, run one command, and upload the resulting dist/ folder anywhere that can serve files.

Your first build

From the repository root, the canonical command is:

// One process: load config, discover content, run features, emit dist/.
const { exitCode } = await build({ cwd: "site" });
console.log(`kiln build finished with ${exitCode}`);

Run it and Kiln prints a report of every page it emitted. The image below is a one-pixel PNG served straight from public/:

What to read next

If you are new to Markdown itself, start with Writing Markdown; if you are curious about metadata, read Frontmatter Fields.