The wizards know the whole file

./blog.sh v1.11 — part 4 of 12

The example config/site.yml is made from has 706 lines, most of them comments. Nobody has to read it all, because there are two wizards for that: ./setup.sh asks what a site needs to stand at all, and ./style.sh asks how it looks. They write the file for you, with no tab where a space belongs, and they write nothing until you have seen the difference and confirmed it.

In 1.10 that was only part of the file, though. What the wizards did not ask, you had to find in the file and write by hand. 1.11 added keys that could be set only there, and the wizards have learned them.

The new questions

./style.sh now asks about:

  • the skin, from the ones the engine ships (classic first, the rest by name, and a skin you dropped into the site yourself, by its file name),
  • the lead card (layout.lead_card), right beside the questions about the sidebar and the lead image,
  • series_contents and series_index, but only on a site that has a series, because elsewhere they would be two more Enters through a section about something the site does not have,
  • the header picture: switched off, the header is the name and the description as text, which suits Minimal Terminal,
  • sharing: which networks under a post, and in which order,
  • tag icons, a section of their own,
  • a series as a menu item, where the archive has one.

./setup.sh asks about:

  • which replies a post shows (comments.approval), and before you choose it says what it costs when only the favourited ones stay,
  • your own PDS for Bluesky, only with an https address,
  • HEIC, repacking video and the location in photos (media),
  • the request to the robots that collect text for AI (seo.block_ai_crawlers).

The last two groups stand behind one question that Enter passes, so a first run stays as long as it was. And a value the site already has is not written over.

What stays with the file

Little is left, and it is rare or it is code: site.author_name, a second language (site.locales), an icon drawn as SVG, the colours of the banner title and claim, mastodon.toot_length and link_length, publishing.allow_partial, seo.robots_extra and deploy.keep. So to say the wizards know the whole file is not quite true. docs/install.md therefore lists what each of them covers and what is left to editing by hand.

What you wrote stays

The second half of this change cannot be seen in the questions. It is seen in the difference the wizard shows before it writes.

A wizard that changed one item of a list wrote the whole list afresh. When one tag icon was added on blogsh.app, every hand-drawn icon_svg went from single quotes to double ones with every quote escaped, a menu of items on one line unrolled into blocks, the comments between items went, and the difference showed twelve changed lines for one new item. The values read the same. The file and the difference did not.

Now the wizard takes a list apart as it stands: each item with its own lines, with the comments and blank lines before it and the column the items stand at. An item equal to one the file holds passes word for word. Only one that is new or changed is written. On copies of blogsh.app, sean.cz and the manual the difference now shows exactly the change: one tag icon is two lines, one share target one, one menu item taken out one.

The exception is a list that cannot be taken apart for sure, written whole on one line (share: [mastodon, email]) or given by an alias. That one is written again, as before. A list the wizard did not change is not written at all.

Back means back

Esc at "which one to remove?" took the first one on offer. A pick among items has no "current" one, so it fell to the first. Backing out of removing therefore removed a hand-drawn icon of a tag that the wizard has no way to put back. Esc at such a pick now chooses nothing and nothing happens. Enter through a whole section changes nothing either: classic on a site that never named a skin, and every switch at a value the engine knows itself, is written as nothing.

Two languages, two files

A language file, config/site.cs.yml, words the menu item by item and has to lead to the same places as the site's own list, or the build refuses the language. But ./style.sh wrote the site's menu and left the language lists as they were. On blogsh.app an ordinary change of the menu left a site that would not build in any language, and the wizard said nothing about it.

Now every language the site publishes whose file has a menu list is reshaped together with the site. An item that stayed keeps that language's word, a new one is written without a word (the build takes the site's own and check says so), and one taken out goes. The language files are shown in the difference with site.yml and written only after your yes.

And when two files are written at once, each is first read in memory. If one of them is refused after the other was already saved, the saved one is put back. "Nothing was changed" then really means nothing.

And env.sh

./setup.sh writes secrets too, that is env.sh. A line that already gives the value is left as it is written (bare, in quotes, with a comment). A line it cannot read for sure is rewritten. A line that assigns two names is left whole even when the first one changes, and the new value goes below it. And the difference before the write masks a secret value anywhere on a line, not only at its start.

What follows from it

Editing the file by hand is a first-class way to use this engine, not an emergency exit, and ./blog.sh doctor is what it was: it reads what you wrote and reports everything at once. But a wizard now does more than offer a starting point. It can be run over a file you have been editing by hand for a year, and it changes only what you asked. And should something still go wrong, it leaves config/site.yml.bak, which takes the run back.

Comments