Written while building this site.

Field notes

This website was started over with verso new and rebuilt in the editor. These are the notes kept along the way: what was a pleasure, what got in the way, and what was fixed because of it.

Four page types, nineteen blocks, seventy pages.

How it was made

The design was set in the Design panel: colours, five font files dropped in, six sizes of type, and the screen sizes cut from ten to five. The page types and most blocks were written by hand, the way a developer would, and then arranged, filled in and corrected in the editor. One block, the list on the 404 page, was made entirely in Build a block from a copy of another.

Every page except the docs articles and the release notes is built from blocks. The header and footer are blocks shared by every page. The changelog is a channel with tags, split four to a page. The last block on the home page is a component, used again on two other pages.

Kept exactly as they are.

What was a pleasure

  • Starting. One command made a site that ran, and renaming it offered to rename the header too.
  • Screen sizes. Each size says how many places use it, so cutting ten down to five took a minute and felt safe.
  • Copying a block. A copy of one block, with “which pages” changed to “the pages beside this one”, was a new block in four clicks. The file changed by one word.
  • Writing a release. Channels, New release, a name, and you're on the page typing. A line that starts with “### ” becomes a heading, “- ” a list.
  • The New page dialog. Every page type is shown as a small live copy of a real page.
  • Publish saying no. “Heading in the Page intro block on Field notes is required, but it's empty” is a sentence anyone can act on.
  • Seeing a phone. The whole page at a phone's width, still editable, one press from the bar.
  • Errors by hand. Four page types, eighteen blocks and sixty-four pages built on the first run. Every mistake after that was named with its file and line.

All twelve are in release 0.11.

What got in the way, and was fixed

  • Fonts. Dropping a font file named the family after the file and gave it one weight. Verso now reads the name, weight and style from the font, and a variable font keeps every weight.
  • Removing a font left its file and its rule behind. They go with it now.
  • Block previews. This site's blocks sit on a white sheet on a dark desk. In the Blocks library and Build a block they were drawn on the bare page: dark text on dark green. A block is now shown inside the same elements as its block area.
  • Adding blocks. Pressing Add closed the library, so three blocks meant opening it three times. It stays open.
  • Renaming a colour closed the Design panel. It comes back where it was.
  • Naming things. “Desk 2” was refused as a colour's name. It's turned into desk-2 as you type.
  • Sub-folders. Fonts added in Design weren't found when a site lived in a sub-folder.
  • Same-day releases were listed 0.9, 0.8, 0.10. Titles now sort the way people read numbers.
  • New page started on the first type in the alphabet. It starts on the type of the page you're on.
  • Picking a colour on a page showed a hundred built-in colours before the site's own six. The site's come first.
  • Classes for your own CSS were errors with no way out offered. The message now says to start them with a hyphen.
  • “Make shades” was the loud button where “Add colour” is the one people want.

All six are in release 0.12.

What was missing, and was added

  • Deleting a page. Page settings has it now, and says what still links to the page.
  • Deleting a block. The builder has a bin. A block in use asks first, then comes off every page.
  • A blank start. verso new my-site --blank makes a home page, a 404 and three plain blocks.
  • Changing an address. Page settings moves the page, and the site's links and lists follow it.
  • Parts in blocks. The showcase card on this site is now written once.
  • A note on Publish. Publish asks what changed, and History shows the answer.
  • Sizes out of order. A class list with its size markers backwards gets a note in the editor, with the file and line.

A correction.

No stylesheet of its own

The first pass at this site had a hand-written stylesheet: about a hundred rules for the stand-in editor bar and the demos on the home page. That missed the point. A Verso site is styled with Elevate classes, so the Design panel reaches everything. The stylesheet is gone, and the bar, the dialogs and the demos are class lists like the rest of the site.

Doing that found four things to fix in Elevate:

  • A script's own value inside class quotes, like class="${look}", stopped the build. Elevate skips it now.
  • line-clamp:2 wrote one property that browsers ignore on its own. It writes the whole set.
  • There was no class for text that only screen readers get. visually-hidden is one.
  • Several grids that shared most of their classes, with three columns starting at tablets on some and at laptops on others, could get each other's columns. Elevate tells them apart now, and only warns about two elements with exactly the same classes.

And three things Elevate doesn't do, which a site like this works around:

  • Classes made while the page runs. Elevate compiles the lists it can read in the files. The Build a block demo writes out every list it can show, fifty-five of them, and looks the choice up. Building a site in Verso never meets this: any class written in a file is compiled when the file is saved.
  • Values that aren't tokens. A swatch showing a colour someone picked, and the size of a scaled preview, are still style attributes.
  • Tokens the browser can change. Tokens are compiled in, so the Design demo swaps colours by rewriting the stylesheet's text, the way the real Design panel previews a change.

Small, and still there.

Still rough

  • The header and footer blocks say “On 1 page” though they're on every page.
  • An empty bullet left at the end of a list is saved.
  • A page made empty gets no heading filled in when its first block arrives.
  • The reason Publish said no names the page, but isn't a link to it.
  • A new site made without installing shows sixty-seven changes waiting on its first open.

Smaller than it was.

What's missing

  • A way in without a terminal. For the people who edit, this is done: release 0.13 runs a site as a box, and they sign in on the site itself. The person who sets the site up still starts with a command.
  • Email. A box doesn't send any, so invites and new-password links are sent by hand.

It takes about a minute.

Start with one page.

One command makes a working site with a few blocks and a page to edit. Open it, click the headline, and change it.

$ npx verso-cms new my-site
Make your first site