Posts and docs that read like prose but can still drop in a real component when it helps.
Lorant
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:
