A tour of the new MDX-powered writing surface — split layouts, pull quotes, galleries, embeds, and the retention mechanics behind the scenes.
Yogesh Mishra
4 days ago5 min read
I rebuilt this blog from scratch. The old one was a single HTML string dumped into a div — fine for a paragraph, hopeless for anything that actually wants to breathe. The new surface is MDX: every post is a file, every layout primitive is a JSX component, and the rules of the page are the rules of the piece.
This post is the showcase. Every component below is one you can reach for when writing.
Splitting the page
The <Split> component is the workhorse. Image on one side, prose on the other. Swap the side, tune the ratio, stack cleanly on mobile.
Text left, image right
This is what a standard editorial split looks like. The image sits flush with the column and the text gets to be text — not a caption, not a sidebar, just writing at a comfortable measure.
Use this when the image is supporting the argument, not carrying it.
Image dominant
When the visual is the point, flip the ratio. The 2:3 here gives the picture more room and the text becomes a deliberate caption-length counterweight.
Works well for product shots, hero moments, diagrams that want to be read first.
Full-bleed moments
Sometimes you want a picture to stop the scroll. <Figure> with aspect="full-bleed" breaks out of the prose column without breaking the layout.
#mdx#nextjs#design#writing
Found this useful?
Tap a reaction — it helps me know what to write next.
Full-bleed images break the column but keep the rhythm — the caption brings you back to the reading measure.
The contained variant keeps things polite:
Contained — stays inside the prose column.
Pulling a thought out of the paragraph
“
The most impressive people I know are all terrible procrastinators. So could it be that procrastination isn't always bad?
Paul Graham·Essayist
Pull quotes are for the sentence you want the reader to feel, not just read. Use them sparingly — one per post is usually enough. Two is a maximum. Three means you should probably cut the piece.
Callouts for the meta layer
Callouts are how you step outside the argument to say something about it. Four variants, each with its own tone:
Galleries
Three images, one row. <Gallery cols={3}> and let CSS grid do the rest.
Numbers that earn their place
The <Stats> component is for the moment you need to land a figure. Count-up triggers on scroll, respects prefers-reduced-motion.
220 wpm
Words per minute
72ch
Characters per line
1.78×
Line height
3+
Psychology hooks per post
Charts when prose isn't enough
Some arguments need a shape. <Chart> is an inline-SVG primitive — no external dep, no client bloat, animates in on view, and respects prefers-reduced-motion. Three types: bar, line, area.
Lighthouse score by route
Score
Audited on a throttled 4G connection, mid-tier mobile.
Time-to-interactive over six releases
ms
Each release shipped one specific optimization — measured, never guessed.
Hover (or focus) any data point for the exact value. The chart doesn't try to be everything; it's there when you have five-to-ten numbers and want them to breathe.
Diagrams and screenshots
Two ways to add diagrams. If you have an image file (screenshot, exported Figma, ER tool export), use <Diagram> — it wraps the image in a labeled, click-to-zoom container with lightbox:
Screenshot
Diagram component — for image-based diagrams. Click to zoom.
If you want to write the diagram as code, use <Mermaid> — it renders flowcharts, ER diagrams, sequence diagrams, class diagrams, and more from text syntax:
Flow Chart
Mermaid component — write diagrams as text, render as interactive SVG. Click to zoom.
ER Diagram
Entity relationships — no external tool needed, just write the syntax.
Use label to describe the diagram type. Good labels: ER Diagram, Flow Chart, Schema, Sequence, Architecture.
Ordered steps and timelines
The <Steps> component is for ordered processes — deploy pipelines, remediation plans, onboarding flows. Not a file tree, not a list — a proper timeline with status indicators.
Writing a blog post
1
Pick the one idea
Put it in a Quote on a scratch line. If it doesn't survive being pulled out, rewrite it.
2
Gather evidence
A Stats row, a Figure, a Gallery, a Mermaid diagram — whatever makes the argument concrete.
3
Set the rhythm
Two Split blocks, a Divider, then tighter paragraphs. Structure before prose.
4
Write the CTA
What should the reader do at the end? A single inline CTA beats three scattered ones.
Showing project structure
The <FileTree> component renders an interactive folder tree — collapsible directories, file-type icons, and optional badges to highlight changes.
Blog system architecture
content
blog
ai-2026-engineering-guide.mdxnew
welcome-to-the-new-blog.mdxnewthis post
src
components
sections
lib
blog
package.json
tsconfig.json
Badges tell the reader what changed: new (green), modified (amber), deleted (red + strikethrough). Annotations after the filename add context without cluttering the tree. Directories auto-sort alphabetically, folders before files.
Code that reads like code
Fenced blocks use Shiki via rehype-pretty-code — server-rendered, zero client cost, with line highlighting syntax ({1,3-5}).
export function estimateReadTime(markdown: string): number { const text = markdown .replace(/```[\s\S]*?```/g, '') // strip code fences .replace(/<[^>]+>/g, '') // strip HTML .replace(/[#>*_`~\[\]()!-]/g, ' '); // strip md punctuation const words = text.split(/\s+/).filter(Boolean).length; return Math.max(1, Math.round(words / 220));}
Inline code like useDeferredValue gets the pill treatment so it doesn't get lost in running text.
Embeds, lazily
YouTube embeds use the lite-youtube pattern — a poster image until you click, then the real iframe. Zero cost on load, full experience on intent.
Dividers when a header is too loud
Dots for a soft break. A plain <Divider /> gives you a hairline. Use them between movements when a new heading would feel like a new chapter.
The retention layer
Everything above is the surface. Under it, the blog runs a handful of small mechanics designed to respect your time and reward your attention:
Reading progress — the hair-thin line at the top of this page tracks how far you've scrolled. No percentages shouted at you; just a quiet signal.
Table of contents — on the right, on desktop. Active section follows your scroll. One click gets you back to a header.
Highlight to share — select any sentence in this article. A small popover offers to quote it on Twitter or copy it. Medium-style, without the ads.
Resume where you left off — close this tab mid-read, come back tomorrow, and a small banner will ask if you want to pick up. Dismiss it and it stays dismissed.
Reactions — three emoji at the end of the post. No accounts, no counts stolen from strangers — just you, your localStorage, and a tiny burst of particles.
Keep reading — near the end of every post, the most related post slides in from the corner. One shot per session, then it's gone.
What to write next
If you're about to write a post in this system, start with the structure, not the prose:
What's the one idea? Put it in a <Quote> on a scratch line. If it doesn't survive being pulled out, rewrite it.
What's the evidence? A <Stats> row, a <Figure>, a <Gallery>.
What's the rhythm? Two <Split> blocks, a <Divider>, then tighter paragraphs.
What do you want the reader to do at the end? A single inline CTA beats three scattered ones.
“
Writing is architecture, not decoration. Pick the load-bearing sentence first; arrange the rest around it.
