Supercharging your Astro Blog with Reusable MDX Components

Apr 8, 2026 · 4 min read ·

showcase components design astro web

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/astro

pnpm add @lucide/astro

yarn add @lucide/astro

Following 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.

Chris Coyier — Co-founder of CodePen