Statac

Problems

Errors, warnings and notes

How to read a problem Statac reports. Problems explained has a page for every kind.

How a problem looks

warning  Broken link: nothing is published at `/about-us/`
  content/post-1.md, line 5
   5 │ Read more [about us](/about-us/).
     │                      ^^^^^^^^^^
  Did you mean `/about/`?
  More: https://statac.dev/e/broken-link/
Part What it says
warning Broken link: ... The kind, then what happened, with your text in backticks.
content/post-1.md, line 5 The file and the line.
5 │ and ^ The line itself, with the exact text marked beneath it.
Did you mean ...? What to do, only where Statac has a good suggestion.
More: A page about that kind of problem. Always there.

A problem in no file, such as a full disk, says what Statac was doing in place of a file and line.

Errors, warnings and notes

Kind What it tells you The build
error What stopped Statac. Stops. Nothing is published, and _site stays as the last build left it.
warning What Statac did in place of what you wrote. Goes on.
note Something Statac did, such as leaving a draft out. Not a mistake. Goes on.

Where Statac is sure what you meant, it does it and warns; where it isn’t, it stops.

A fault in Statac itself is none of these. Statac prints Rust’s own report of it, ending Report it at https://github.com/statac-ssg/statac/issues, with the lines above.

An error ends the command with 1, warnings and notes leave it at 0, and a fault ends it with 101: see exit codes.

What does build show?

3 warnings: 2 dates-disagree, 1 broken-link.
4 notes: 3 no-site-address, 1 untitled-page. Run `statac check` to see them.

Made 4 copies of 1 photograph.
Wrote 7 pages and 6 other files to `_site` in 0.03 seconds.

statac build counts warnings and notes by kind, a line for each, and shows every error in full:

error  Missing file: there is no `assets/sit.css`
  templates/base.html, line 14
  14 │ {{ css("sit.css") }}
     │    ^^^^^^^^^^^^^^
  While building: content/404.md
  And while building 9 more:
    content/index.md
    content/posts/index.md
    content/posts/post-1.md
    content/posts/post-2.md
    content/posts/post-3.md
    and 4 more. Run `statac check` to see them.
  Did you mean `site.css`?
  More: https://statac.dev/e/missing-file/

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

Wrote nothing: 1 error stopped the build.

A mistake in a template that many pages are built through is one problem, shown once with the first page that met it and up to five more.

One warning only a build can find is shown in full: nothing made.

What does check show?

statac check

check builds the site as build does, but writes nothing and runs no command of your own. It shows every problem in full, with every page each was met on, then counts them as build does. Two notes are check’s alone: hook not run and location published. With nothing to report, it says No problems.

It also lists the JavaScript the site carries:

JavaScript the site carries:
  `/app.01c5c780.js` from `assets/app.js`, on 1 page

Quieten a kind you have understood

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 takes the names of warnings and notes. check stops showing them, and both commands still count them. Where every one is quietened, the line says so: 3 warnings, all quietened.

An error can’t be quietened, nor a problem that leaves a page out, such as a draft left out.

Read about a kind in the terminal

statac explain broken-link

A kind’s name is the last part of its More: link. statac explain prints the page that link leads to, offline.

Once every page is built, Statac follows every link on every page, as a browser would.

A link to Is held to
An address on the site Pages, feeds, files from assets/ and static/, files beside the writing, and old addresses that send readers on. Otherwise it is a broken link.
#part of a page The id of a heading, a footnote or an element of that page’s HTML. Otherwise it is a missing anchor.
Another site Nothing: a build fetches nothing.
A path in not_ours Nothing: something else publishes there.

Both are warnings, and the page is published with the link as written. Each is shown once, at the line that wrote it. Links inside an HTML file published as it is aren’t followed.

A link naming the site’s own host, or a host in also_at, is a link into the site. On a site under a path, such as /blog/, a link written from / leads outside it: write it with @url(...).

Colour

Statac colours its messages on a terminal. A file or another program gets none.

Set What it does
NO_COLOR, to anything Turns colour off everywhere.
CLICOLOR_FORCE=1 Turns it on where Statac would leave it off, such as into a pager that shows colour.
TERM=dumb Leaves it off: the terminal says it can’t show colour.
COLORTERM, to truecolor or 24bit Statac’s own orange is shown exactly, not as the nearest of 256 colours.

Where next?

Something unclear or wrong? Open an issue on GitHub.