Add page furniture to a post
- 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 if you have not chosen a format yet. Setup and publishing are in the 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: the takeaways box is the first layer, details elements hold the deepest.
- Answer first: a summary box says the answer; callouts mark the supporting points.
- Situation, Complication, Resolution: a callout for the complication helps the reader see the turn.
- It also decorates scrollytelling and walkthroughs 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
:::
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
detailsor 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.
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.