Upgrading to 0.7.0

Statac 0.7.0 is a breaking release. Settings, template names and problems take the words you would search for, Statac writes no templates into a site, and it makes nothing a site doesn’t ask for.

Most of what changes stops the build, and the error names the fix. A few things change without a word: what Statac no longer makes, code colours and dates. Read those before you publish the first build.

Before you upgrade

Keep a record of what the site publishes now, so the first build with 0.7.0 can tell you what it no longer publishes. With 0.6, build the site, then, in the site’s folder:

(cd _site && find . \( -name index.html -o -name '*.xml' \) | sed 's|^\.||; s|index\.html$||' | sort) > published.txt

This writes published.txt with the URL of each page and feed. The first build with 0.7.0 then warns of each one it no longer publishes, such as a folder’s feed:

warning  URL gone: `/notes/feed.xml` was published before, and nothing is there now
  published.txt, line 10

Without the file, the first build starts published.txt afresh and can’t tell what went. Commit published.txt with the site.

What stops the build

An old name, in statac.yaml, in front matter or in a template, stops the build, and Statac says what to write in its place:

error  Unknown setting: `left_behind`
  statac.yaml, line 4
   4 │ left_behind: [drafts]
     │ ^^^^^^^^^^^
  Statac calls this `exclude`.

later_pages:, pages.later:: pagination.permalink:
left_behind:: exclude:
not_ours:: served_elsewhere:
also_at:: other_hosts:
after_build_makes:: after_build_outputs:
page.photo(), page.photos(): page.image(), page.images()
page.words: page.word_count
A video’s still: thumbnail
page.webmentions.said, .faces: .comments, .reactions
A mention’s face, words: avatar, content
In snippets/markdown/: address, outside, photo: url, external, image

A template name read only inside {% if %}, such as {% if page.photo %}, is never reported: the test is false, and the branch writes nothing. Search your templates and snippets for each old name in the table.

Fifteen problem names change, among them same-address (now same-url), undescribed-picture (missing-alt-text), missing-words (missing-translation) and waiting-for-its-day (scheduled-post). Four go, with what they reported on: missing-address, not-a-web-address, newer-starter and code-colours-not-loaded. In quiet: or statac explain, a renamed problem’s old name stops with the new one offered, and a retired one with “This kind of problem no longer exists.” The old names’ pages under Problems explained redirect: a renamed problem’s to its new page, a retired one’s to a related page.

These stop the build too, each with its fix:

code_style. Statac carries no themes: write code_colours: true in its place, and copy the theme’s rules from Code colours into a stylesheet of the site’s own. A template’s {{ css("code.css") }} stops the build until you take it out. See code colours.
fetched/refused. Statac prints the refuse_webmentions_from: lines to add to statac.yaml, then delete the file. A line now refuses everything at or under its URL.
A tag’s or a series’ url, with no list page. Statac makes tag and series pages only where you ask: add tags.pages: true or series.pages: true to statac.yaml. The error offers a default filter, but statac check notes the setting to add.
image: or images: in front matter. Statac fills page.image itself, so it sets these fields aside with a warning: rename them, such as cover:. word_count: is set aside too.
Calls and settings 0.6 let through: a snippet called with a hyphen in its name, such as @my-snippet; a language’s settings, such as en.title, on a site in one language; and pages.order: with a list of names, which goes in the folder’s index.md as order:.

What Statac no longer makes

Statac makes no page or file that nothing asked for. A site that relied on what 0.6 made builds without it, with no error:

The site’s feed: From 0.7.0 Only with feed: true in statac.yaml; Always
A folder’s feed: From 0.7.0 Only with feed: true in the folder’s index.md; Every top-level folder
Paginated pages: From 0.7.0 Only where posts_per_page is set; 10 posts a page
Tag and series pages: From 0.7.0 Only with tags.pages: true or series.pages: true, or a page of yours; Always
The home page: From 0.7.0 Only with content/index.md or templates/home.html; Always
A folder’s list page: From 0.7.0 Only where the folder has an index.md; Always

statac check notes a feed template that no list uses, and a tag with no list page. A lost folder feed or paginated page has no note: the published.txt made before upgrading catches them. See which lists have a feed and pagination.

A page with no template is published as its content alone, and a redirect with no template as a page that sends the browser on.

Code colours

Without code_colours: true, Statac writes code with no classes, and nothing says so, even where the site’s stylesheet still colours them. To keep 0.6’s colours:

Write code_colours: true in statac.yaml, in place of code_style.
Copy the rules of the theme code_style named into a stylesheet of the site’s own: Ocean, 0.6’s default, if the site had no code_style.
Take {{ css("code.css") }} out of your templates.

Statac reports an unknown code language, or code it can’t colour, only with colours on.

Dates

Each language’s dates now follow CLDR, the Unicode Consortium’s data on languages. Without date_format:

language: en, en-US, en-CA and en-PH write “December 31, 2025”. en-GB, en-AU, en-NZ, en-IE, en-IN and the other English regions keep “31 December 2025”.
A region takes its own words: de-AT writes “31. Jänner 2025”.
On en-CA or es-MX, a time written with 3 and no a.m. or p.m., such as date("3:04pm"), stops the build.

To keep the dates as they were, set date_format, such as date_format: 31 December 2025. A site made by 0.6’s statac new already has one. Its date_short, date_day and date_stamp keep working, as custom settings; a template can name a look instead, such as date("short"). See how dates look.

HTML that changes

Task lists: each box is now inside a <label>: <li><label><input type="checkbox" disabled checked> Done</label></li>. A selector such as li > input needs li > label > input.
Code: no hl- classes without code_colours: true.

Other changes

exclude: takes a path, such as blog/drafts/. In 0.6 a path matched nothing, so files it names now drop out of the build.
New notes may appear on a site that built cleanly: links, buttons, iframes and form fields with no text for a screen reader, and a page with no <title>. See Problems explained.
published.txt is new at the top of the site. Commit it.

Commands

statac new --update, --missing, --cards, --no-starter: Gone, with nothing in their place: Statac writes no templates into a site, so there is nothing for them to update or add.
statac refuse <url>: refuse_webmentions_from:, a list of refused URLs in statac.yaml
--site=: Gone: name the site’s folder after the command, as statac build my-site.

New sites

statac new asks five questions (the site’s title, the author’s name, the site’s URL, its language and its time zone) and writes statac.yaml with the answers, a .gitignore, and an empty content/ folder, with a file of words to translate for a language Statac has only some words for. statac import writes no templates either. A site made before 0.7.0 keeps every file: its templates are its own. Drop-ins has templates and snippets to copy, for feeds, social cards, search and the rest.

Installing

Statac’s code, issues, Homebrew tap and Scoop bucket are on git.statac.dev. If you installed with brew install statac-ssg/statac/statac, brew upgrade statac keeps working. New installs use the commands in Installing.

Also new

Editors: problems as you type, completion, hover and renaming a page with its links, in Sublime Text, VS Code and Zed.
statac check --json prints the problems for another program, and statac build --timings shows where a build spent its time. See Building and publishing.
Serving a site with no home page shows a list of the pages it built at the top of the site.