Context
This sample article uses MDX when plain Markdown starts to feel too cramped. The layout, metadata, sidebar, and footer still come from the shared site shell.
Checklist
- Start with the visible strings and menu labels.
- Rename helper functions before writing conclusions.
- Keep screenshots and diagrams inside the post folder.
- Document uncertainty instead of pretending the first pass is complete.
Before You Start
Do not turn MDX posts into custom one-off pages. The goal is richer article bodies, not custom chrome.
What we tracked first
We started from user-facing strings, mapped the surrounding helper calls, and only then guessed at the broader flow. That kept the article grounded in visible evidence.
Second image example
Template example posts should also demonstrate that a single article can carry more than one colocated image without changing anything about the surrounding site layout.
Why MDX helps here
The reusable callout, figure, and comparison blocks make the article easier to scan without forcing contributors to build page structure from scratch.
Pros
- Shared components keep the post body structured.
- Junior contributors can reuse existing patterns quickly.
- Local images stay near the post.
Cons
- MDX is slightly more complex than Markdown.
- It is easier to over-design the article body if no one reviews the structure.
Takeaway
Use MDX when the body clearly benefits from components. If the article is still mostly headings and paragraphs, fall back to regular Markdown.