A series is a chapter

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

The manual for this engine, kept at manual.blogsh.app, has 75 pages in ten chapters, and every chapter is a series of posts. Up to 1.10 that was a series the menu knew nothing about. A menu item could point at a tag, a page or an address. A series address could go in there, but it did not light up on the series' own parts, so a reader in the middle of a chapter could not tell they were in one.

1.11 mends that with four things that belong together and can each be switched on alone.

A series as a menu item

nav:
  - { label: "Home", url: "/" }
  - { label: "Photos", tag: "photos" }
  - { label: "First steps", series: "First steps" }

A series: item takes the series' name as the posts write it, or its slug, and leads to its listing. It lights up on every part of the series, but differently than on the listing itself: the listing is the page you are on, a part is the chapter you are in. A screen reader gets two different values of aria-current, "page" and "true", a skin gets two selectors, and every skin the engine carries draws them differently.

The listing of a series exists only once the series has two published parts. Until then the item leads to a 404, and doctor says so.

A heading over the chapters

A menu of twenty chapters is a list nobody remembers. An item with group: true and a label, and no destination, is a heading over the items after it, up to the next group:

nav:
  - { label: "Start here", url: "/start-here/" }
  - { label: "Basics", group: true }
  - { label: "Installing", series: "Installing" }
  - { label: "Writing", series: "Writing" }
  - { label: "Running it", group: true }
  - { label: "Deploying", series: "Deploying" }

The list stays flat. ./style.sh writes a group like any other item, and the file of the second language names it the same way. A group with nothing under it is left out, and an address written on a group is never followed. doctor names both.

How a group is drawn is up to the skin. Classic and Minimal keep the items in one row and the label stands in front of them as a quiet caption; on a phone it is a heading above them. Manual turns it into a heading over the chapters in the side menu.

Every part knows the others

layout:
  series_contents: true

On the page of every part there is a list of all the parts of the series, under the "part N of M" line and above the text, and the one you are reading is marked. The list is never shortened, however long the series runs. It is off until you ask for it. It is the permanent navigation of a manual whose chapters are series.

The list of series

The /series/ page with the listing of all the series got its entry in 1.10. Now it also has a title, a description and an order:

series_index:
  title: "Chapters"
  description: "Every chapter of the manual, in the order it was written."
  order: oldest

order: oldest sorts the series by the day each began, so in the order the manual was written. Without it the series with the newest part stands first. The file of the second language may give its own title and description.

The guide thinks of it

./style.sh asks about the skin and about the lead card. If the site has a series, it also asks about series_contents and series_index, and offers the series as a menu item. You do not have to write any of those three keys by hand.

What follows from it

A series stays one thing: one address, one set of parts. What is new is that the menu can point at it, and that a reader inside it always sees where they are. A manual, a travel diary or a course by lessons, anything that has chapters, can be built from posts and does not have to leave the engine for it.

How it looks when the chapters stand in the side menu is shown by the guide to the Minimal Manual skin.

Comments