Special offer: 20% off all plans this month!

Products

Resources

Pricing

Log in

Sign up

March 17, 2025

Example blog post 1

Lorant and Once UI

Designing and writing with MDX

MDX lets you write content that feels like a blog post — while still giving you access to real components, layout primitives, and interactive elements.
This post is a short walkthrough of how MDX can be used to create clean, expressive, production-ready content.

Structuring your thoughts with headings

Clear structure makes content easier to scan and easier to read.
Use headings to guide the reader through ideas, not just to break text apart.

Smaller sections for supporting ideas

Subheadings work best when they introduce a clear shift in focus, rather than repeating the main headline.

Going deeper when necessary

You rarely need more than three levels of hierarchy, but MDX supports it when you do.

Use sparingly

Deep heading levels are most useful in technical writing or long-form documentation.

Writing readable paragraphs

MDX is still Markdown at its core, which means writing feels natural and distraction-free. You can emphasise ideas with bold text, add nuance with italics, or combine both when something really matters. The goal isn’t decoration — it’s clarity. Good content reads well even before styling is applied.

Lists that explain, not overwhelm

Lists are great for breaking down ideas, steps, or options.

When order doesn’t matter

Clear visual hierarchy
Easy to skim
Works well for features or highlights
- Nested points add context
Avoid overly long lists

When sequence matters

Start with the core idea
Add supporting details
End with a clear takeaway

If a list starts feeling heavy, it’s usually a sign it should be rewritten as prose.

Showing code in context

Sometimes the clearest explanation is a small code example. Inline snippets are useful for quick references like npm i @once-ui-system/core, while larger ideas benefit from fenced blocks:

Tsx

export default function Hello() {
  return <h1>Hello world!</h1>
}