Supercharging your Astro Blog with Reusable MDX Components
Writing documentation and tech blogs can often feel repetitive and, visually, quite monotonous. Walls of text aren’t fun to read, but with MDX (Markdown + JSX) running on Astro, we can easily inject interactive, beautifully styled React-like components right into our posts.
In this post, we’ll walk through how we transformed a standard markdown blog into an interactive learning experience using a custom design system.
Warning the Reader (Gracefully)
Sometimes you need to grab the reader’s attention quickly. Maybe a dependency is deprecated, or there is a security vulnerability they should be aware of. Instead of bold text, we built a universal <Callout /> component.
Note
Did you know? The latest version of Astro allows you to use standard markdown alongside mdx files seamlessly within your collections!
Pro Tip: Use TypeScript
When writing complex framework components, leveraging TypeScript can heavily reduce run-time errors by catching prop validation issues early.
Breaking Change
I recently migrated from Astro v3 to v5. Please ensure your content.config.ts has been correctly updated to use astro:content.
Interactive Installation Guides
When documenting a library, giving your developers choices is essential. Notice how many top-tier docs offer npm, pnpm, and yarn installation options? With our custom <Tabs> component, providing this functionality is completely frictionless:
npm install @lucide/astropnpm add @lucide/astroyarn add @lucide/astroFollowing the Process
Instead of standard unordered lists (<ul>) which often blur into the rest of the text, we created a <Steps> component that automatically renders a clear vertical timeline for tutorials:
Step 1: Initialize your project
Run npm create astro@latest and choose the blog template to instantly get a highly optimized site scaffolding.
Step 2: Add Tailwind CSS
Run npx astro add tailwind to securely install the latest version of Tailwind into your UI layer.
Step 3: Write MDX
Add the @astrojs/mdx plugin and start writing content instantly!
First-class Code Formatting
I decided to integrate Expressive Code. This is an Astro integration that automatically adds amazing capabilities to your code blocks without even using a custom Component. All natively in MDX!
---import Layout from '../layouts/Layout.astro';import { getCollection } from 'astro:content';
const posts = await getCollection('post');---<Layout title="Welcome to my Blog"> <main> <h1>Hello World</h1> </main></Layout>MDX is a format that lets you seamlessly write JSX in your Markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content.
Highlighting Information
When reviewing frameworks or methodologies, a ProsCons list is invaluable for your readers to digest the benefits quickly:
Pros
- • Visually stunning pages out-of-the-box
- • Higher reader engagement metrics
- • Enforces strict design system consistency
Cons
- • Increases initial build-time slightly
- • Requires author to remember component syntax
Sometimes explaining complex architectural concepts requires video. I built a zero-layout-shift YouTube embedder natively for MDX:
And if you ever need to reference external documentation, instead of a standard hyperlink, use a <LinkCard>:
Astro 5.0 Release
Astro 5 is here and brings a new Content Layer API, improved type safety, and better build performance.
astro.build
With these components, your technical blog won’t just be informative—it will be an experience. 🎉