---
name: explainer-page-furniture
description: Add helpful page elements to a Bloggo post so a text explainer is easier to follow, such as side notes, definitions, callouts, timelines, key takeaways, expandable details and before-and-after comparisons. Use when a post is mostly prose but readers need terms explained, a summary up front, a timeline, or a comparison.
compatibility: Needs the explainers feature on the blog (GET /v1/features lists it).
---

# Page furniture

Small elements that sit around the prose and help it do its job. They work in any post and combine with the other formats. Start with the [explainer skill](https://skill.bloggo.blog/posts/explainer/) if you have not chosen a format yet. Setup and publishing are in the [Bloggo skill](https://skill.bloggo.blog/posts/bloggo-skill/).

## When it fits

- The post is mostly prose, and the reader needs a term defined, a summary up front, or a detail that would interrupt the flow.
- A timeline or a comparison would replace a long paragraph.
- Use sparingly: a page full of boxes is harder to read than plain text. Two or three kinds, a handful in all, is plenty.

## Structure to pair it with

- [Layered](https://skill.bloggo.blog/posts/explainer-structure-layered/): the takeaways box is the first layer, details elements hold the deepest.
- [Answer first](https://skill.bloggo.blog/posts/explainer-structure-answer-first/): a summary box says the answer; callouts mark the supporting points.
- [Situation, Complication, Resolution](https://skill.bloggo.blog/posts/explainer-structure-scr/): a callout for the complication helps the reader see the turn.
- It also decorates [scrollytelling](https://skill.bloggo.blog/posts/explainer-scrollytelling/) and [walkthroughs](https://skill.bloggo.blog/posts/explainer-annotated-walkthrough/) outside their blocks.

## Elements

**Summary and takeaways.** Put a summary after the title and takeaways at the end.

```
::: summary
Interest compounds: you earn on your earnings. Over 30 years that doubles the result of simple interest.
:::

::: takeaways
- Start early, because time matters more than the amount.
- Check the rate you actually pay, not the advertised one.
:::
```

**Callout.** Types are `note`, `tip`, `warning` and `key` (the one idea to remember). Use at most one `key` per post.

```
::: callout {type=warning}
Rates shown here are examples, not offers.
:::
```

**Definition.** A term defined inline, shown on tap or hover, and as plain text in the raw `.md`. Keep definitions under 25 words and define a term once.

```
The [APR]{define="Annual percentage rate: the yearly cost of borrowing, fees included"} is higher than the headline rate.
```

**Side note.** A short aside that sits in the margin on wide screens and under the paragraph on phones. Keep it to one or two sentences.

```
Compound interest grows exponentially.^[Exponentially means the growth itself keeps growing.]
```

**Details.** A closed section for depth most readers can skip. The title must say what is inside.

```
::: details {summary="How the calculation works"}
Each year's interest is added to the balance before the next year's interest is computed.
:::
```

**Timeline.** A bulleted list where each item starts with a bold date or label, then a dash.

```
::: timeline
- **1969** - First message sent over the network.
- **1983** - The network adopts a common protocol.
:::
```

**Compare.** Two images of the same size, the before and the after, with a slider to reveal one over the other. Each has alt text and the first one is the "before".

```
::: compare
![The page before the redesign](/media/01J.../before.png)
![The page after the redesign](/media/01J.../after.png)
:::
```

Where the slider cannot run, the two images are shown one above the other.

## Rules

- Write the plain-text meaning first. If you removed every element the text would still read well; each element only adds help.
- Do not hide anything essential in `details` or definitions. Hidden text is read less.
- Callout text is short, never more than two sentences. Longer means it belongs in the body.
- A block with an unknown type or option is drawn as its content in plain Markdown. Fix it from the note in the save reply.
- Math and code have their own rules in [math-and-code-blocks](https://skill.bloggo.blog/posts/math-and-code-blocks/).

## Mistakes

- Using a callout for every important sentence. If everything is important, nothing is.
- Jargon with no definition, or a definition for every word. Define only what the target reader does not know.
- Takeaways that repeat the title. They should add the consequence: what to do or decide.