Statac

Shape the site

Settings

statac.yaml, at the top of a site’s folder, holds the site’s settings.

Write a setting

In statac.yaml:

title: Site
url: https://example.org/
language: en-GB
timezone: Europe/London
date_format: 31 December 2025

Every line is optional: a site with only a content/ folder still builds. Each setting is one line, with its whole name before the colon, as pages.layout: post. url: ~ is read as though the line weren’t there. A name that isn’t one of Statac’s, such as tagline:, is a value of your own.

The site

Setting What it does Default
title The site’s name, site.title in templates. Feeds need it. None
url The address the site is published at, starting https:// or http://, site.url in templates. Feeds, sharing cards, webmentions and pages with needs: url wait for it. None
language The site’s language as a code, such as en, en-GB or fr, site.language in templates. A site in several lists them, the main one first: [ar, en]. en
timezone The zone your clock is in, such as Europe/London. A date with no offset is read in it, and it decides what today is. UTC
<code>.title title for one language: en.title: Notes. title
tagline A value of your own, the starter’s feed’s <subtitle>. None
author A value of your own: who writes the site, in the starter’s feed and at the foot of its pages. None

A url with a path, such as https://example.org/blog/, makes a site in a folder of its domain.

Dates

Setting What it does Default
date_format How dates look, written as an example. 31 December 2025, or the language’s own usual form
<code>.date_format date_format for one language: en.date_format: Dec 31, 2025. date_format
date_zeros false drops the leading zero from the day and the month where the month is in figures: 4/3/2026, not 04/03/2026. true
date_short, date_day, date_stamp Values of your own, not settings: the shorter dates the starter’s templates need. None

Writing and code

Setting What it does Default
typography false leaves quotes, --, --- and ... in the writing as typed: see punctuation. true
code_style The colours of code in the writing: ocean, gruvbox, solarized, catppuccin or one-half. ocean

Lists

Setting What it does Default
posts_per_page How many posts each page of a list shows, 0 for all of them on one. A list’s page can say its own. 10
later_pages Where a list’s later pages go: a pattern opening {list}, holding {n} once and ending with /. Only in statac.yaml. {list}page/{n}/
tags.permalink, series.permalink Where the page for each tag, and each series, goes: a pattern ending {slug}/. /tags/{slug}/, /series/{slug}/
tags.pages, series.pages false makes no such pages. The lists still work in templates. true
tags.slugs, series.slugs A tag’s or a series’ own part of its address: each name on a line beneath the setting, as C++: cpp. None
pages.<name> Hands a field down to every page: pages.layout: post, or pages.untitled: true for a site whose pages go without titles. A folder’s line, or the page’s own, comes first. None

Pictures

Setting What it does Default
max_width The widest copy Statac makes of a photograph, in pixels: a whole number from 1. 1600
image_sizes How wide photographs are shown on the page, written as the sizes of an <img>. (max-width: 46rem) 100vw, 46rem
optimise_images false makes no copies of any photograph: each is published as it is. true

Change what Statac makes has more.

Feeds

Setting What it does Default
feed_key What each post’s id in a feed is made from. statac new writes one fresh: once a feed is published, never change it. None
feed_ids_before A day, for a site moving from another tool: each post dated before it keeps its whole address as its id. None
feed_ids_from jekyll: with feed_ids_before, those posts keep the id Jekyll’s feed gave them instead. None
write_feed_ids true has statac serve and statac stamp write an id: line into each post in a feed that statac build hasn’t yet published from this computer, and into a post that has moved, the id it had. statac build never writes one. false

pages.feed: false gives the site no feeds. See entry ids and when a post moves.

Webmentions

In statac.yaml:

url: https://example.org/
webmentions: true

webmentions: true says the site receives webmentions. They need url.

Warning:

The relay’s token is never written in statac.yaml: a webmention_token: line stops the build. The token says where it goes.

Quieten a kind of problem

In statac.yaml:

quiet: [dates-disagree]
1 warning: 1 broken-link, and 2 quietened.
4 notes: 3 no-site-address, 1 untitled-page. Run `statac check` to see them.

quiet names the kinds of warning and note you have understood. statac check stops showing them; build and check still count them. A kind’s name is the last part of its More: link.

An error can’t be quietened, nor anything that leaves a page out. Errors, warnings and notes explains each kind.

Commands of your own

Setting What it does Default
before_build A command run before the site is read, such as one that makes a stylesheet. None
before_build_watches The files and folders the before_build command reads, a folder ending with /: [styles/]. None
after_build A command run on the built files once the site is built with no errors, before they are published. None
after_build_makes The files and folders the after_build command makes, from the top of the built site: [search/]. Links into them are taken to land. None

build, serve and check differ in which they run: see when each command runs.

Setting What it does Default
also_at Other hosts the site is published at, such as [www.example.org]. A link naming one is checked as a link into the site. None
not_ours Paths on the site’s host that something else publishes, from the top of the host: [/video/]. Links into them are left unchecked. None
left_behind Names in content/ that are never published. Writing the line replaces the whole list. .DS_Store, Thumbs.db, desktop.ini

Fields and types

Setting What it does Default
fields.<name> What kind of value one of your own fields holds, and whether every page must have it: fields.isbn: required text. A nested field is named in full: fields.book.author: text. None
types.<type>.<name> The same, for the pages of one type: types.book.isbn: required text. None

Declare your fields has every kind. A field can also name a record in data/, as fields.author: one of data.people: see a field that names a record.

Values of your own

In statac.yaml:

book:
  author: Author 1
  isbn: 0-000-00000-0

Any line that isn’t one of Statac’s settings is a value of your own, which a template shows as site. and its name: {{ site.book.author }}. It may nest, as book: does, and may hold a list.

Some names are kept for what Statac gives templates, such as today, posts, pages and fields.

For one run

statac build --url=https://preview.example.org/42/

statac build and statac check take --url in place of url for one run, such as a preview at another address. Build options has the rest.

Where next?

Something unclear or wrong? Open an issue on GitHub.