MDX Styling Solution for Tailwind CSS

Problem

When using Tailwind CSS, its normalization removes default styling from HTML elements. This means that MDX-rendered content (like h1, p, ul, li, etc.) loses its styling and appears unstyled.

Solution

We’ve implemented a comprehensive MDX styling system that automatically applies custom classes to all MDX-rendered elements.

How It Works

1. MDX Components Styling (src/components/MDXComponents.astro)

This file contains global CSS that targets all HTML elements within .mdx-content containers:

• Headings (h1-h6): Properly sized with spacing and borders
• Paragraphs (p): Optimized line height and spacing
• Lists (ul, ol, li): Custom bullets and proper indentation
• Links (a): Blue color with orange hover effect
• Code (code, pre): Syntax highlighting ready
• Tables (table, th, td): Professional styling with hover effects
• Images (img): Rounded corners and shadows
• Blockquotes: Orange left border with background

2. BlogPost Layout Integration

The BlogPost.astro layout includes:

• Import of MDXComponents.astro for styling
• Application of .mdx-content class to the main content area
• Responsive design considerations

3. Astro Configuration

Updated astro.config.mjs to ensure both MDX and Markdown files use consistent styling:

• Disabled default syntax highlighting to use rehype-pretty-code
• Added rehype plugins for better code highlighting
• Configured consistent theme across formats

Special Features

DIY Project Styling

Special styling for common DIY blog sections:

• Materials sections: Blue headers
• Tools sections: Orange headers
• Step sections: Green headers

Cost Breakdown Tables

Tables containing cost information get special green theming.

Image Captions

Italic text following images is automatically styled as captions.

Responsive Design

All elements adapt properly on mobile devices with adjusted font sizes and spacing.

Usage

1. For new MDX files: Just write normal Markdown/MDX content - styling is applied automatically
2. For existing files: No changes needed - the styling is applied globally
3. Custom styling: Add elements inside the .mdx-content container to inherit styling

File Structure

src/
├── components/
│   └── MDXComponents.astro          # Global MDX styling
├── layouts/
│   └── BlogPost.astro               # Includes MDX styling
└── content/
    └── blog/
        ├── *.mdx                    # MDX files (styled automatically)
        └── *.md                     # Markdown files (styled automatically)

Example MDX Content

---
title: "My DIY Project"
description: "A simple tutorial"
---
 
# How to Build Something
 
This is a paragraph that will be properly styled.
 
## Materials Needed
- Item 1 (will have custom bullets)
- Item 2
- Item 3
 
### Step 1: Prepare
Follow these instructions...
 
| Item | Cost |
|------|------|
| Wood | $20  |
| Screws | $5 |
 
*This table will have special cost styling*

All content will be automatically styled without any additional work required!