Write a scrollytelling explainer

Scrollytelling

The reader scrolls through short paragraphs. Beside or behind them, one visual stays in place and changes when the text reaches the matching step. Bloggo draws it from plain Markdown: you supply the visuals, the words and a few options, and Bloggo owns the layout and motion. Start with the explainer skill if you have not chosen a format yet. Setup and publishing are in the Bloggo skill.

When it fits

• A change over time (a map in 1900, 1950, today), a process in stages, a chart that gains a line, code that grows, a diagram where parts light up one by one.
• Three to eight visual states that really differ. With fewer, use page furniture or plain figures. With more, split into two explainers.
• Not for reference material that readers will search or skim, and not when the visual says nothing the text does not. For explaining one object part by part, use the annotated walkthrough.

Structure to pair it with

• And, But, Therefore for a story with tension, one beat per step.
• How it works for a process or mechanism, one stage per step.
• Situation, Complication, Resolution for the opening paragraphs before the scrolly block starts, so the reader knows why they are scrolling.
• Answer first fits badly: scrolling is about discovery. Put the answer in the summary and the opening paragraph, then use the scrolly to show why.

Syntax

A scrolly block holds stickies (the visuals, each with an id) and steps (paragraphs). A step that contains [@id] shows that sticky; steps without a reference keep the sticky already on screen, with the same zoom, pan or highlight as the step before.

::: scrolly {side=right}

::: sticky {#coast1900}
![Coastline in 1900, town at the river mouth](/media/01J.../coast-1900.png)
:::

::: sticky {#coast1990}
![Coastline in 1990, harbour and two new districts](/media/01J.../coast-1990.png)
:::

In 1900 the town was a handful of houses by the river. [@coast1900]

The harbour changed that, and the town followed the water outwards. [@coast1990 zoom=2 pan="30% -20%"]

:::

• side is left, right (default) or center. It says where the text column sits; on a phone the visual always sits above the text.
• A sticky holds exactly one of: an image (with alt text, and a diagram is an image: SVG and PNG both work), a fenced code block, or a table.
• Reference options, all optional: zoom (1 to 3) and pan (two percentages from -100 to 100, x then y; the picture moves by that share of its size, so pan="-25% 0%" shows more of its right side when zoomed) for images, highlight (line numbers or ranges, such as highlight="3-5") for code, and rows (table body rows, such as rows="2-3") for tables. Unknown options or values out of range make the block fall back to plain text.
• The first sticky is shown from the start. Ids are lowercase letters, digits and dashes, unique within the post.
• Everything outside a scrolly block is ordinary Markdown. Do not nest a scrolly inside another block.

Use the same image size for all image stickies, or the page jumps. A code sticky must stay readable on a phone: at most about 12 short lines.

How to write one

1. Write the story as 3 to 8 steps first, one sentence each. Each step must teach one new thing.
2. Decide what the visual shows at each step. If two steps would show the same picture, merge them or let the second be a step without a reference.
3. Make or collect the visuals. Upload images with POST /media. For a diagram, draw an SVG yourself and upload it. Keep sizes and style the same.
4. Write each step in 25 to 60 words. Start with what changed, then why it matters.
5. Open with one or two paragraphs outside the block that say what the reader will understand, and close with one outside the block that sums it up.
6. Save as a draft and open the preview. Scroll it: does the right visual match each paragraph?

Checks

• Every sticky is referenced at least once, and every reference exists.
• Alt text for each image says what changed since the last one.
• Read the text alone, with the visuals removed. It must still tell the story, because feeds, search engines and the raw .md show only the text.
• Nothing important depends on motion. Readers who ask their system for less motion get the visuals without animation.

Mistakes

• A visual per sentence. It makes the page restless. One state change per paragraph is the limit.
• Text on top of detail in the picture. Keep important parts of an image away from the text column.
• A step that explains two things, or has a long list. Split it or move it into the opening text.
• Ending on the last visual with no conclusion. Add a short closing paragraph after the block.