Everything that's wrong, at once

Every abort in this engine is correct where it stands. Each one also reports exactly one problem — the first one, from wherever in the code it happened to be noticed. Fix it, run again, meet the next one. Repeat until the thing builds.

./blog.sh doctor reads what is on disk and tells you the lot in one pass, in whole sentences, each with a fix line written for somebody who does not know which file that setting lives in.

It goes after the silent failures

A loud error at least announces itself. The problems doctor concentrates on are the ones that never say anything:

• An unknown timezone. Ruby falls back to UTC without a word, and every post is dated wrong from then on.
• A banner whose declared size no longer matches the file. Every page jumps as it loads, and nothing anywhere is broken enough to complain.
• A widget that can never show anything — configured with the wrong kind of identifier, rendering an empty box forever.
• A font named in the config but missing from assets/fonts/. The browser silently falls back and the site is simply not the site you designed.
• A deploy backend configured half way.
• The example's text still sitting where visitors would read it — the about box that still describes a blog engine's sample site rather than yours.

--online additionally asks whether the feeds, the analytics script and the access token still answer. Tokens expire quietly; that is their nature.

It runs when nothing else will

This is the part that took the most care. Doctor works on configurations too broken for anything else to load — including one whose YAML will not parse, which is exactly the moment you want it.

Related, and shipped alongside: a YAML syntax error in config/site.yml is now a sentence rather than a Psych backtrace from whichever entry point happened to read the file first. It names the line, the column, the three usual causes — a tab where spaces belong, a missing quote, a colon inside an unquoted value — and points at doctor.

Errors and advice are different things

Exit status is non-zero for errors only. Warnings are advice, and advice that fails your build is not advice.

That distinction is why doctor is safe to put in a cron or a pre-deploy check: it will stop you when something is actually wrong, and merely talk when something is merely worth knowing.

Why bother, on a tool this small

Because "it doesn't work and I don't know why" is where people give up, and the engine's own failure modes were the ones most likely to produce that sentence. The abort messages were all accurate. Accuracy one problem at a time is still a maze.