Skip to content
GitHub

Blog#

Kiln can build a blog: a directory of dated markdown posts, rendered as individual post pages plus the listing pages a blog needs — a paginated index, per-tag pages, author pages, and an RSS feed. It’s the engine behind blog.vapor.codes.

A blog is additive to a KilnSite: posts are discovered by scanning a directory, not declared in navigation. Enable it by passing a Blog:

import Kiln

let site = KilnSite(
    name: "Vapor",
    url: "https://blog.vapor.codes",
    description: "News and articles from the Vapor team.",
    blog: Blog()
)

try await Kiln.build(site, contentDirectory: "Content", outputDirectory: "site")

Single-language, unversioned

A site with a blog must be single-language and have no versions: — this keeps post URLs free of version and locale prefixes. The blog index is the site root, so a blog site has no index.md.

Writing a post#

Each *.md file in the posts directory (posts/ by default, under your content directory) becomes a post at /posts/<filename>/. The leading # Heading becomes the title and is stripped from the body.

---
date: 2024-09-03 09:00
description: A short summary used for cards, SEO, and the RSS feed.
tags: swift, release
author: tim
image: /images/posts/my-post.png
---
# My first post

Everything below the title is the post body…
Front matter Purpose
date Publish date, parsed with the blog’s dateFormat. Sorts posts newest-first.
description Summary for cards, <meta> description, and the RSS feed.
tags Comma-separated; each becomes a tag page.
author / authorImageURL A single author (a registry username or a literal name).
authors / authorImageURLs Semicolon-separated, for co-authored posts.
image Per-post social/OpenGraph image (falls back to the site default).

What Kiln generates#

From the posts directory Kiln produces:

URL Page
/posts/<slug>/ Each post.
/, /2/, … Paginated index, newest-first.
/tags/, /tags/<slug>/ Tag directory and per-tag listings (paginated).
/authors/, /authors/<slug>/ Author directory and per-author listings (paginated).
/feed.rss RSS 2.0 feed.

Each post also carries BlogPosting + BreadcrumbList JSON-LD and is added to the sitemap and search index.

Authors#

Posts reference an author by username in front matter. Register authors on the Blog to give them a name, photo, bio, and social links — Kiln then builds an author page (/authors/<username>/) listing their posts, with ProfilePage / Person JSON-LD:

blog: Blog(
    authors: [
        Author(
            username: "tim",
            name: "Tim",
            imageURL: "/author-images/tim.jpg",
            description: "Core team member.",
            github: "0xTim",
            mastodon: "https://hachyderm.io/@0xtim",
            website: "https://timc.dev"
        ),
    ]
)

A post with author: tim then links its byline to that author page (matching is case-insensitive). The typed social fields — github, twitter, mastodon, bluesky, linkedin, instagram, website, plus a links: array for anything else — each render with the right icon. An author: value with no registry match falls back to a plain display name.

Configuration#

Blog() works with sensible defaults; every option is overridable:

Option Default
postsDirectory "posts" Where post markdown lives, under the content dir.
postsPerPage 8 Posts per page on the index and tag/author listings.
feedTitle / feedDescription site name / description RSS channel metadata.
indexTitle site name Heading on the index.
tagsTitle / authorsTitle "Tags" / "Authors" Headings on the directories.
dateFormat "yyyy-MM-dd HH:mm" Parses each post’s date: (fixed en_US_POSIX/UTC).
displayDateFormat "d MMMM yyyy" How dates render on pages and cards.
readingWordsPerMinute 200 Divisor for the reading-time estimate.
authors [] The author registry.

Theming#

The bundled theme ships templates for every blog page (blog-post, blog-index, blog-tags, blog-author, and partials). Override any of them with a custom theme — drop a same-named .leaf file in your theme directory and Kiln uses yours instead.

Edit this page