Building Beautiful Blog Posts with MDX Components

MDX is a powerful format that combines Markdown with JSX, allowing you to use React components directly in your content. This post demonstrates all the custom MDX components available for creating rich, interactive blog posts.

Callout Components

Callouts are perfect for highlighting important information. We have four types available, each with its own visual style and icon.

Info Callout

Use info callouts for general information or notes that readers should be aware of.

Tip Callout

Tips are great for sharing best practices and helpful suggestions.

Warning Callout

Warnings help readers avoid common pitfalls or potential issues.

Danger Callout

Danger callouts are for critical information that could cause serious problems if ignored.

Code Blocks

Code blocks support syntax highlighting for various languages. They also include a convenient copy button that appears on hover.

TypeScript Example

1interface BlogPost {
2  title: string;
3  slug: string;
4  excerpt: string;
5  publishDate: string;
6  tags: string[];
7  author: string;
8  featured?: boolean;
9}
10
11async function fetchBlogPosts(): Promise<BlogPost[]> {
12  const response = await fetch("/api/posts");
13  if (!response.ok) {
14    throw new Error("Failed to fetch blog posts");
15  }
16  return response.json();
17}

React/TSX Example

1import { useEffect, useState } from "react";
2
3interface Props {
4  initialCount?: number;
5}
6
7export function Counter({ initialCount = 0 }: Props) {
8  const [count, setCount] = useState(initialCount);
9
10  useEffect(() => {
11    console.log(`Count changed to ${count}`);
12  }, [count]);
13
14  return (
15    <div className="flex items-center gap-4">
16      <button onClick={() => setCount((c) => c - 1)}>-</button>
17      <span className="text-2xl font-bold">{count}</span>
18      <button onClick={() => setCount((c) => c + 1)}>+</button>
19    </div>
20  );
21}

CSS Example

1.glass-effect {
2  background: rgba(255, 255, 255, 0.05);
3  backdrop-filter: blur(10px);
4  border: 1px solid rgba(255, 255, 255, 0.1);
5  border-radius: 1rem;
6}
7
8.gradient-text {
9  background: linear-gradient(135deg, #00d4ff, #7c3aed, #f472b6);
10  -webkit-background-clip: text;
11  -webkit-text-fill-color: transparent;
12  background-clip: text;
13}

Link Cards

Link cards provide a visually appealing way to reference external resources. They automatically extract the domain and display it below the description.

Video Embeds

Embed videos from YouTube or Vimeo with automatic URL parsing. The component supports different aspect ratios and optional captions.

YouTube Video

Tables

Tables are styled automatically with proper borders, padding, and alternating row colors for better readability.

Feature Comparison Table

Blockquotes

Blockquotes are styled with a distinctive left border and subtle background to make them stand out from regular text.

The best way to predict the future is to create it.

-- Peter Drucker

You can also use blockquotes for longer passages:

MDX bridges the gap between content and code. It allows content writers to focus on writing while giving developers the flexibility to create rich, interactive experiences. This combination makes MDX an excellent choice for documentation, blogs, and any content-heavy application.

Lists

Unordered Lists

Here are the key benefits of using MDX:

• Flexibility: Mix Markdown with React components seamlessly
• Reusability: Create components once, use them everywhere
• Type Safety: Full TypeScript support for component props
• Developer Experience: Hot reloading and familiar React tooling
• Content Management: Easier to manage than pure JSX files

Ordered Lists

Steps to create an MDX blog post:

1. Create a new .mdx file in the content directory
2. Add frontmatter with title, slug, and other metadata
3. Import any components you need at the top of the file
4. Write your content using Markdown syntax
5. Insert React components where needed
6. Preview your post in the development server
7. Commit and deploy your changes

Nested Lists

Project structure for an MDX-powered blog:

• content/
  • blogs/
    • my-first-post/
      • index.mdx
      • images/
    • another-post/
      • index.mdx
• src/
  • components/
    • mdx/
      • callout.tsx
      • code-block.tsx
      • link-card.tsx
      • video-embed.tsx
  • lib/
    • mdx.ts

Combining Components

The real power of MDX comes from combining multiple components to create rich content experiences.

Here's a quick reference table followed by relevant resources:

Diagrams

Visualize complex systems and workflows with Mermaid diagrams and Excalidraw embeds. These components render beautiful, interactive diagrams directly in your blog posts.

Flowchart: Authentication Flow

Flowcharts are perfect for illustrating processes and decision trees. Here's an authentication flow diagram:

Sequence Diagram: API Request with Caching

Sequence diagrams show interactions between different components over time:

Entity Relationship Diagram: Blog Schema

ER diagrams help visualize database schemas and relationships:

State Diagram: Newsletter Workflow

State diagrams are ideal for modeling system states and transitions:

Excalidraw: Hand-drawn Style Diagrams

For a more informal, whiteboard-style look, use Excalidraw embeds. Great for brainstorming, architecture sketches, or explanatory drawings:

Conclusion

With these MDX components, you can create engaging, interactive blog posts that go beyond traditional Markdown. Each component is designed to be:

1. Easy to use - Simple, intuitive APIs
2. Accessible - Built with accessibility in mind
3. Customizable - Styled to match the site's design system
4. Performant - Minimal JavaScript footprint

Happy writing!