aneym

Posts that do more than sit there

A field guide to the interactive building blocks in this blog — callouts, steps, expandable explainers, and figures — and why a paragraph isn't always the right tool.

·1 min read·meta · writing · design

Most technical writing is a wall of prose with the occasional screenshot. That's fine for a changelog. It's a poor fit for explaining how something works — where the reader needs to follow a sequence, peek at a detail without losing the thread, or see state change.

So the posts here have a small kit of interactive parts. Here's the starter set.

Callouts

For the aside that shouldn't interrupt the sentence but shouldn't be missed either.

Note

The neutral one — context, caveats, "by the way" asides.

The actual point

The one that earns the orange. Use it sparingly or it stops meaning anything.

Watch out

For the footgun you already stepped on so the reader doesn't have to.

Steps

When order matters, a numbered rail beats "first… then… after that…" buried in a paragraph. Each step animates in as you reach it.

1

Write in MDX

A post is a folder with an index.mdx. Frontmatter up top, prose and components below.

2

Drop in components

Use <Callout>, <Steps>, <Figure> directly — no imports. They're themed by the active design tokens.

3

Push to publish

Flip status: published, commit, push. The deploy is automatic.

Expandable detail

Some explanations have a layer underneath that most readers can skip. Nest it instead of derailing the main line of thought.

Figures

A framed, captioned container for an image — or, soon, a live interactive visual that knows how to export itself as a GIF for places that only take pictures.

your visual here

Figures wrap a visual in a themed frame with a caption. Live components go here next.

Code, with a button

Code blocks are highlighted at build time and get a copy button on hover:

post.mdx
export const meta = {
  title: "Posts that do more than sit there",
  status: "published", // flip this, push, done
}

That's the kit so far. The interesting part — visuals that render live here and export as GIFs for Twitter — is what I'm building next.