Commands of your own

Statac has no plugins. A command of your own, named in statac.yaml, runs before the build or after it.

Run a command before or after the build

In statac.yaml:

before_build: ./styles.sh
after_build: ./upload.sh

Each is one line for your system’s shell, sh on macOS and Linux and cmd on Windows. It runs in the site’s folder with nothing to read from: a command that asks a question gets no answer, and goes on.

When each command runs

Serving a site while you write shows what serve prints as it runs each one.

What a command is handed

Each folder is given as a whole path. sh writes a value as "$STATAC_OUT", and cmd as "%STATAC_OUT%". Keep the quotes: the path may hold a space.

Make files before the build

In statac.yaml:

before_build: ./styles.sh
before_build_watches: [styles/, tokens.json]

before_build_watches names the files and folders the command reads, from the top of the site’s folder, a folder with a / at its end. Each must be there. statac serve runs the command again whenever a save touches one.

Upload the built site

In upload.sh, beside statac.yaml:

#!/bin/sh
[ "$STATAC_SERVE" = yes ] && exit 0
rsync -a "$STATAC_OUT"/ example.org:www/

A build given --url for a preview doesn’t tell the command the address, so the command publishes the preview.

Act on STATAC_OUT, never on _site by name. Statac builds into a folder of its own, and puts it in _site’s place only once the whole build, your command included, has ended well.

Compress the built files

On macOS and Linux, in statac.yaml:

after_build: find "$STATAC_OUT" -type f \( -name '*.html' -o -name '*.css' \) -exec gzip -k -f {} \;

This makes a compressed copy of every page and stylesheet, as index.html.gz beside index.html, for a web server to send. The build counts what the command added:

Ran `after_build`, which added 2 files.

A file it writes over is counted as changed, and one it takes away as removed:

Ran `after_build`, which added 2 files and changed 1.
Ran `after_build`, which added 2 files, changed 1 and removed 3.
Ran `after_build`, which added 0 files and changed 1.

Tell Statac what after_build makes

In statac.yaml:

after_build: ./index.sh "$STATAC_OUT"
after_build_makes: [search/, search.json]

Statac checks every link on the site, and a link to a file the command makes later would be broken. after_build_makes names what the command makes, from the top of the built site, a folder with a / at its end. A link into search/, or to search.json, is then taken to land.

When a command stops

With after_build: echo to-out; echo to-err >&2; exit 3 in statac.yaml, statac build prints:

error  Hook stopped: `after_build` ended with exit code 3
  statac.yaml, line 10
  10 │ after_build: echo to-out; echo to-err >&2; exit 3
     │              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  What it printed:
    to-out
    to-err
  More: https://statac.dev/e/hook-stopped/

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

Wrote nothing: 1 error stopped the build.

Any exit code but 0 stops the build: Statac says how the command ended, shows what it printed, the last 40 lines where there are more, and publishes nothing. The site built last time stays as it was.

• What a command prints is shown only when it stops. To see it otherwise, run the same line yourself in the site’s folder.
• A command that leaves something running in the background keeps the build waiting until that ends too.
• Under serve, a command that stops stops that round. Serve goes on, and the next save tries again.

Run only commands you trust

A command runs as you, with no limit from Statac: it can read, change and remove your files, and send them anywhere. Only statac.yaml can name one.

Where next?

• Search: a search box, with an indexing tool that after_build runs, or with none
• Serving a site while you write: what serve prints as it runs your commands
• Building and publishing: putting the built site on a host
• Settings: everything else in statac.yaml