8 Recipes

Two complete, copyable setups: a personal blog and a documentation book. Each one shows the directory layout, the config, and the key front matter, with notes on the parts that bite. 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. Which kind of project depends on one thing: 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 (a grid)
├── 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: grid
---

## 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: grid
---

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 from one 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 simply ignored: it is a page key, and it is not a _site.yml key at all. 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.