Format for documents

• Take for example this snippet: the following is executed: antora site.yml. The convention generally used is that commands are typed using a monospace font, like antora site.yml here.
• The $source-state restore way of writing a command actually looks weird to me, havn't seen it anywhere (have you?). Again, using a monospace font is the way to show it's a command. The $ is commonly used when command are given on a separate line, but not in running text "This script has 3 options:" This statement is actually plain wrong. First options refers to things with dashes, like -l or --quiet. A word without dashes is an argument. And, there is only one argument, which could have one of three values. If you write for a more skilled reader, she would be happy if you first gave the formal description as given in a manpage source-state-sh <restore|update|save> Of course, you still need to explain it. But when for example I read that, I immediately understand that the script has a mandatory argument which is one of restore, update or save.
• 'sources.state' is better typed using italics, like sources.state. The general approach is that paths and filenames are using italics while commands are using monospace.
• You seem to avoid using subheadings, instead using a bullet list (plugins.adoc, nav-plugins.adoc, etc.) It works, but unfortunately the bullet list headings does not appear in the navigation tree in the right panel :(