A theme describes itself and configures a few behaviours here, without touching a template. This is what the built-in themes use:
title: "Ink" description: "A clean, minimal theme" version: "1.0.0" author: "FolioPress"
meta: supports_dark_mode: true responsive: true categories: [minimal, portfolio]
settings: # free-form; available to templates as theme_settings primary_color: "#2563eb"
home: posts: 10 # how many posts the home page receives order_by: "-published_at" # newest first has_pagination: false # a cutoff, or real page links? image_ratios: poster: "16:9" # what the admin's cropper offers for this page type gallery: "free"
page: { posts: 10, order_by: "-published_at", has_pagination: false } post: { posts: 3, order_by: "-published_at" } # related posts under a post tag: { posts: 12, order_by: "-published_at", has_pagination: true }
page-about: # override for one page, by its primary-language slug image_ratios: { poster: "1:1" } post-tutorials: # override for posts whose first tag has this slug image_ratios: { poster: "4:3" }
Key What it controls
title, description, version, author Shown on the admin’s Themes page.
meta.supports_dark_mode, meta.responsive, meta.categories Descriptive; used for the theme gallery.
meta.social_image A file in the theme's static/, drawn at 1200x630, used as the link-preview image when a page has no poster image of its own. Without it such a page shares as the 180x180 touch icon.
settings Anything you like. Handed to every template as theme_settings, so a colour or a tagline can live here instead of in CSS.
home, page, post, tag The list of posts that template type receives: posts (how many), order_by, and whether has_pagination adds real page links or just cuts the list off.
order_by -published_at (newest first) or published_at; likewise created_at and updated_at, with or without the leading -; or random.
image_ratios What the admin’s image cropper offers when editing that content type: a ratio like 16:9, a list of them, or free. Separate values for poster and gallery.
page-<slug>, post-<tag-slug> The same keys, overriding page/post for one page (by its primary-language slug) or for posts whose first tag has that slug.