Building and publishing

From a site on your computer to one on the web.

Build the site

statac build

3 notes: 3 no-site-address. Run `statac check` to see them.

Made 60 copies of 11 photographs.
Wrote 17 pages and 66 other files to `_site` in 0.19 seconds.

The finished site goes in _site, in the site’s folder. Warnings and notes are counted first.

Statac keeps the copies of photographs in .statac/, so only a site’s first build or serve makes them and prints the Made line: see the first build.

Nothing is published unless the whole build succeeds. If anything stops it, _site stays as the last build left it.

Change how it builds

Which site is built?

statac build docs

A folder named after the command, or with --site, must be a site itself, with a statac.yaml or a content/ folder: Statac never looks above it.

With no folder named, Statac builds the site the current folder is in, so it runs from any folder inside the site, such as content/posts.

Put it on a host

_site is the whole site as plain files, for any web host: copy what is in it to wherever the host serves from. A file the build didn’t change keeps its date, so a tool that copies only newer files copies only what changed.

To upload after every build, make the upload an after_build command. It acts on the folder STATAC_OUT names, before that folder replaces _site.

A preview at another address

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

--url gives one build another address, in place of url in statac.yaml, such as a host’s build of each change before it is published.

What --url changes:

• site.url, site.host and the absolute filter, and so the feeds, the sitemap, robots.txt and the sharing tags your templates write.
• An address with a path makes a site in a folder of its domain, as url does.
• A site with no url yet has its feeds, its sharing cards and its needs: url pages published.

What it doesn’t:

• Addresses and paths written out, in your writing or a template. A link to https://example.org/post-1/ still leads to the site, not the preview.
• Drafts and posts waiting for their day stay out without --drafts.
• Nothing marks the site as a preview, so a search engine that can reach it may list it. A template can tell a preview by site.host.
• Each post keeps its feed id, the preview shows the site’s webmentions, and webmention() names the site’s own host.

Unless --out names another folder, a build with --url replaces _site; the next build without it puts the site back at its own address.

The spare

The spare is a second copy of the built site, in .statac/spare in the site’s folder. With it, a build writes only the files that changed.

A build brings the spare up to date, then swaps it with _site in one step, so _site is whole at every moment. Every build still makes the whole site: a file changed, added or removed in _site by hand is put back.

• You can delete the spare at any time. The next build writes every file.
• You can delete all of .statac/, but two things in it can’t be made again: the feed record and the webmention token, if you keep it there.
• It takes as much room as the built site.

Check before you publish

statac check

check reads and builds the site as build does, but writes nothing and runs no command of your own. It shows every problem in full, and lists any JavaScript the site carries. build shows errors in full and counts warnings and notes by kind.

check takes --site, --today, --drafts and --url as build does. Errors, warnings and notes explains each kind.

Exit codes in scripts

A build with warnings and no errors ends with 0.

Where next?

• Commands of your own: run a command before or after each build, such as an upload
• Errors, warnings and notes: each kind of problem, and quietening one
• Addresses: choosing addresses, and a site in a folder of its domain