8 Recipes

Two complete, copyable setups: a personal blog and a documentation book. Each one shows the directory layout, the config, and the main front matter, with notes on the parts that are easy to get wrong. Copy the closest one and edit it down; the configuration and cell options references have the full list of keys.

8.1 Books, sites, and the difference

Point either command at a directory and Taliesin builds a project instead of a single page. The kind of project depends only on whether that directory’s _site.yml lists chapters:. If it does, the directory is a book, no type: key needed; if it doesn’t, it’s a website whose pages you compose from front matter, the shape recipe 1 below shows.

The two forms navigate differently, too. A page with toc: true gets a table of contents built from its own headings, a sidebar rail on a wide screen. A book gets no such rail: its Chapters drawer lists every chapter instead, since what a reader of a book needs is the neighbouring chapters, not the current one’s headings.

8.2 1. A personal blog

A home page that lists recent posts, a blog.tmd index over a posts/ folder, and an about.tmd profile, all generated from front matter.

blog/
├── _site.yml
├── index.tmd            # home: about header + "recent posts" listing
├── blog.tmd             # the full post index
├── about.tmd            # a profile page
├── profile.webp
├── favicon.svg
└── posts/
    ├── first-post/
    │   ├── index.tmd
    │   └── thumbnail.webp
    └── second-post/
        └── index.tmd

A post is its own folder so its images and any .bib live next to it. Page discovery walks the whole tree, so posts/first-post/index.tmd is a real page; the listing crawls the same folder to build the cards.

The project config, _site.yml:

title: "Jane Doe"
description: "Notes on things I'm learning"
url: "https://example.com"
favicon: favicon.svg
nav:
  - { text: Blog, href: blog.tmd }
  - { text: About, href: about.tmd }
footer:
  left: "© 2026 Jane Doe"
  right:
    - { icon: github, href: "https://github.com/jane" }

The home page leads with a hero: header and fills a listing: with the two most recent posts. The id: makes the listing fill a ::: {#recent} block where you put it, instead of appending to the end of the page:

---
title: "Jane Doe"
hero:
  headline: "Jane Doe"
  lead: "Notes on things I'm learning."
toc: false
listing:
  id: recent
  contents: posts
  max-items: 3
  type: list
---

## Recent posts

::: {#recent}
:::

[View all posts →](blog.tmd)

The full index, blog.tmd, is a listing-only page with the visible <h1> suppressed:

---
title: "Blog"
title-block-style: none
listing:
  contents: posts
  type: list
---

Each post supplies what the card shows (title, date, description, image, and a badge per category) through its own front matter:

---
title: "My first post"
description: "What it's about, in one sentence."
date: 2026-05-08
image: "thumbnail.webp"
image-alt: "A scatter plot of the fitted model"
categories: [machine learning, statistics]
---

8.3 2. A documentation book

Numbered chapters grouped into a part, a Chapters drawer, and Cmd-K search, all generated from the chapters: list.

handbook/
├── _site.yml
├── index.tmd            # the cover / preface
├── intro.tmd
├── setup.tmd
├── usage.tmd
└── reference.tmd

Taliesin numbers the chapters, builds the Chapters drawer, wires prev/next navigation, and resolves cross-references across chapters. The full grammar of a chapter entry is in Configuration; the _site.yml for the tree above is:

title: "The Handbook"
author: "Jane Doe"
chapters:
  - index.tmd
  - intro.tmd
  - part: "Using it"
    chapters:
      - setup.tmd
      - file: usage.tmd       # { file:, text: } overrides the chapter label
        text: "Everyday use"
  - reference.tmd

The Chapters drawer is a book’s whole navigation, so a chapter’s own toc: is ignored: it is a page key, and it is not a _site.yml key. The Cmd-K (Ctrl-K) search palette indexes every chapter, and the book output directory defaults to _book/ instead of _site/. The chapter pages themselves need no special front matter; a plain title: is enough:

---
title: "Introduction"
---

Without an explicit text: override, the chapter label is the chapter’s first # heading, then its front-matter title:, then the file name.