Errors and error handling

Like every static website generator, soupault is a non-interactive program that cannot ask the user what to do if something goes wrong. Most errors are caused by configuration mistakes, so the user would want to fix the configuration anyway, rather than make a one-time correction. With non-interactice programs, it's especially important to have a clear mental model of what the program is doing and where it may fail.

For the record, here's a simplified flowchart of what soupault is doing:

Now let's discuss things that are considered errors, and also things that you may think are going to be errors but in reality they aren't.

Many widgets have a selector option that defines either the source element to extract something from, or the target element to insert something into, depending on context. For example, for the title widget it's the element it will take text from and put into the <title> tag inside the page head. For the include widget, it's the element where file content is inserted. Usually it's obvious whether it's source or destination (or so I hope), but when in doubt, you can always consult the reference manual.

Anyway, why I'm talking about it: it's important to remember that absense of an element matching the selector option is never considered an error. If soupault cannot find a suitable element for a widget to work with, it assumes you just don't want that widget to run on that page and does nothing.

That's a compromise made to give you more freedom. For example, suppose you have this config for the ToC:

[widgets.table-of-contents]
  widget = "toc"
  selector = "#generated-toc"
  ...

If you want a table of contents only in some pages rather than in every page, you can omit the <div id="generated-toc"> from templates/main.html and include it in select page files instead. The widget will run on pages where it's present and skip the pages where it's absent.

This behaviour can sometimes be counterintuitive and can actually hide errors. For example, the exec widget will not even try running a script if it has nowhere to insert its output anyway, so if you mistyped the script path or made another mistake, you will not notice it until you have page where that widget does run.

If you expect something to happen but it doesn't happen, it's a good idea to inspect the output of soupault --verbose. Some widgets explicitly tell you why they didn't run, though some don't and it's something to improve in future versions.

On the other hand, most widgets will fail if they can't do what they are supposed to do. For example, the include widget will fail is the file it's supposed to include doesn't exist or isn't readable. The exec widget will fail if the script you want it to run doesn't exist or cannot be successfully executed.

If a required widget option is missing, that's also an error and you will also receive an error message about it.

This kind of errors can be treated as fatal or not, as discussed in a previous post. When the strict = true option is configured in the [settings] section of soupault.conf, soupault will stop running and exit immediately when it runs into an error. If that option is false, it will just print a warning and continue processing pages, they just will not include the output those widgets were supposed to produce.

One limitation of soupault 1.3 is that errors in Lua plugins, no matter how serious, are never treated as fatal. Soupault will print warnings and errors, but otherwise it will proceed as if nothing has happened. That's also something to fix in the future.