Skip to content
@jordanlee

Writing with MDX: callouts, tabs, and captions

1-minute read
on this page

Most posts on this site are plain Markdown. Every now and then a post needs a callout, a set of tabs, or a snippet with a file name — and that is what .mdx is for. Rename the file, keep writing, and the components below are available without any imports.

Callouts

Tabs

Tabs are handy for specs that differ by format:

  • A5, 148 × 210 mm, 3 mm bleed
  • Uncoated 120 gsm, black only
  • Exported as PDF/X-4
  • 1440 px wide artboards, 8 px grid
  • Images exported at 2×, WebP
  • Type set in the same two faces as print
  • 1080 × 1350 px portrait
  • One idea per frame, no more than eight words
  • Alt text on every post

Snippets

Code blocks are rendered by Expressive Code. A title turns the block into a small editor frame, which is a tidy way to share the odd bit of CSS or a settings file:

type.css
:root {
--font-heading: 'Dela Gothic One', sans-serif;
--font-sans: 'Space Grotesk Variable', sans-serif;
}
h1 {
font-family: var(--font-heading);
letter-spacing: 0.05em;
}

Captions

An image on its own line with alt text becomes a figure with a caption — no components needed:

Morning light on the tiles of Alfama
Morning light on the tiles of Alfama

When to stay in Markdown

If a post has no callouts, tabs, or components, keep it .md. Plain Markdown is faster to build, easier to preview in any editor, and portable to whatever you migrate to next.