## Introduction MDX is a powerful format that combines the simplicity of Markdown with the flexibility of React components. This guide will show you how to create engaging, interactive blog posts using MDX. ## What is MDX? MDX allows you to write JSX directly in your Markdown files. This means you can: - Use React components within your content - Create interactive elements - Maintain the readability of Markdown - Add rich media and custom styling ## Front Matter Structure Every MDX blog post starts with YAML front matter that defines metadata: ```yaml --- title: "Your Post Title" excerpt: "Brief description of your post" publishedAt: "2025-12-16T21:00:00Z" updatedAt: "2025-12-16T21:00:00Z" tags: ["tag1", "tag2", "tag3"] featured: true interactive: true components: ["ComponentName1", "ComponentName2"] author: name: "Your Name" email: "your.email@example.com" bio: "Your bio" seo: title: "SEO Title" description: "SEO Description" keywords: ["keyword1", "keyword2"] ogImage: "/images/og-image.jpg" --- ``` ### Key Fields Explained - **`title`**: The main title of your post - **`excerpt`**: A brief summary shown in post listings - **`publishedAt`**: Publication date in ISO format - **`tags`**: Array of tags for categorization - **`featured`**: Boolean to highlight important posts - **`interactive`**: Set to `true` if using React components - **`components`**: List of custom components used in the post - **`seo`**: Optional SEO overrides for better search visibility ## Basic Markdown Syntax MDX supports all standard Markdown syntax: ### Headings ```markdown # H1 Heading ## H2 Heading ### H3 Heading #### H4 Heading ##### H5 Heading ###### H6 Heading ``` ### Text Formatting - **Bold text** using `**bold**` - *Italic text* using `*italic*` - ~~Strikethrough~~ using `~~strikethrough~~` - `Inline code` using backticks ### Lists Unordered lists: - Item 1 - Item 2 - Nested item - Another nested item Ordered lists: 1. First item 2. Second item 3. Third item ### Links and Images ```markdown [Link text](https://example.com) ![Alt text](image-url.jpg) ``` ### Code Blocks Use triple backticks with language specification: ```javascript function greet(name) { return `Hello, ${name}!`; } console.log(greet("World")); ``` ```python def fibonacci(n): if n <= 1: return n return fibonacci(n-1) + fibonacci(n-2) print(fibonacci(10)) ``` ### Blockquotes > This is a blockquote. It can span multiple lines and is great for highlighting important information or quotes from other sources. ### Tables | Feature | Markdown | MDX | |---------|----------|-----| | Headers | ✅ | ✅ | | Lists | ✅ | ✅ | | Code | ✅ | ✅ | | Components | ❌ | ✅ | | Interactive | ❌ | ✅ | ## MDX-Specific Features ### Using React Components MDX allows you to use React components directly in your content. The blog system provides several built-in components: #### Custom Images Instead of regular Markdown images, you can use the enhanced image component: ```jsx ``` #### Custom Links Enhanced links with better styling and external link handling: ```jsx Visit Example.com ``` #### Code Blocks with Syntax Highlighting ```jsx {`interface BlogPost { title: string; content: string; publishedAt: Date; }`} ``` #### YouTube Videos Embed YouTube videos easily with the YouTube component: ```jsx ``` Different sizes: ```jsx ``` Advanced options: ```jsx ``` Or use a full YouTube URL: ```jsx ``` ### Interactive Elements You can create interactive content using React components: ```jsx

💡 Pro Tip

Use interactive elements sparingly to enhance your content without overwhelming readers.

``` ### JavaScript Sandbox (Full JavaScript Support) For complete JavaScript freedom, use the JavaScriptSandbox component: #### Interactive Vector Field Animation

Field Strength: 1.0 Vector Density: 20

Move your mouse over the canvas to influence the vector field!

`} css={` .vector-container { text-align: center; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; } #vectorCanvas { border: 2px solid #234F1E; border-radius: 8px; background: linear-gradient(135deg, #f8fffe 0%, #f0f8f0 100%); cursor: crosshair; display: block; margin: 0 auto 20px; box-shadow: 0 4px 12px rgba(35, 79, 30, 0.1); } .controls { display: flex; justify-content: center; gap: 20px; flex-wrap: wrap; margin-bottom: 15px; } .controls label { display: flex; align-items: center; gap: 8px; font-size: 14px; color: #234F1E; font-weight: 500; } .controls input[type="range"] { width: 100px; } .controls span { min-width: 30px; font-weight: bold; color: #1a3d17; } #resetBtn { background: #234F1E; color: white; border: none; padding: 8px 16px; border-radius: 6px; cursor: pointer; font-weight: 500; transition: background 0.2s; } #resetBtn:hover { background: #1a3d17; } .info { color: #666; font-style: italic; margin-top: 10px; } `} javascript={` const canvas = document.getElementById('vectorCanvas'); const ctx = canvas.getContext('2d'); const strengthSlider = document.getElementById('strength'); const densitySlider = document.getElementById('density'); const strengthValue = document.getElementById('strengthValue'); const densityValue = document.getElementById('densityValue'); const resetBtn = document.getElementById('resetBtn'); let mouseX = canvas.width / 2; let mouseY = canvas.height / 2; let fieldStrength = 1.0; let vectorDensity = 20; let animationId; // Vector field parameters let time = 0; const baseField = []; // Initialize base field function initializeField() { baseField.length = 0; for (let x = 0; x < canvas.width; x += vectorDensity) { for (let y = 0; y < canvas.height; y += vectorDensity) { baseField.push({ x: x, y: y, baseVx: Math.sin(x * 0.01) * Math.cos(y * 0.01), baseVy: Math.cos(x * 0.01) * Math.sin(y * 0.01) }); } } } // Calculate vector at position influenced by mouse function calculateVector(x, y, t) { // Distance from mouse const dx = x - mouseX; const dy = y - mouseY; const distance = Math.sqrt(dx * dx + dy * dy); const maxInfluence = 150; // Base field (swirling pattern) let vx = Math.sin(x * 0.008 + t * 0.02) * Math.cos(y * 0.008); let vy = Math.cos(x * 0.008 + t * 0.02) * Math.sin(y * 0.008); // Mouse influence (attractive/repulsive force) if (distance < maxInfluence && distance > 0) { const influence = (maxInfluence - distance) / maxInfluence; const mouseForce = fieldStrength * influence * 2; // Create a swirling effect around mouse const angle = Math.atan2(dy, dx); const perpAngle = angle + Math.PI / 2; vx += Math.cos(perpAngle) * mouseForce * 0.5; vy += Math.sin(perpAngle) * mouseForce * 0.5; // Add some attraction/repulsion vx += Math.cos(angle) * mouseForce * 0.3 * Math.sin(t * 0.05); vy += Math.sin(angle) * mouseForce * 0.3 * Math.sin(t * 0.05); } return { vx: vx * fieldStrength, vy: vy * fieldStrength }; } // Draw a single vector arrow function drawVector(x, y, vx, vy) { const magnitude = Math.sqrt(vx * vx + vy * vy); if (magnitude < 0.01) return; const scale = 15; const endX = x + vx * scale; const endY = y + vy * scale; // Color based on magnitude const intensity = Math.min(magnitude * 100, 255); const red = Math.floor(35 + intensity * 0.5); const green = Math.floor(79 + intensity * 0.3); const blue = Math.floor(30 + intensity * 0.2); ctx.strokeStyle = \`rgb(\${red}, \${green}, \${blue})\`; ctx.lineWidth = Math.max(0.5, magnitude * 2); // Draw vector line ctx.beginPath(); ctx.moveTo(x, y); ctx.lineTo(endX, endY); ctx.stroke(); // Draw arrowhead if (magnitude > 0.1) { const angle = Math.atan2(vy, vx); const arrowLength = 4; ctx.beginPath(); ctx.moveTo(endX, endY); ctx.lineTo( endX - arrowLength * Math.cos(angle - Math.PI / 6), endY - arrowLength * Math.sin(angle - Math.PI / 6) ); ctx.moveTo(endX, endY); ctx.lineTo( endX - arrowLength * Math.cos(angle + Math.PI / 6), endY - arrowLength * Math.sin(angle + Math.PI / 6) ); ctx.stroke(); } } // Animation loop function animate() { // Clear canvas with gradient background const gradient = ctx.createLinearGradient(0, 0, canvas.width, canvas.height); gradient.addColorStop(0, '#f8fffe'); gradient.addColorStop(1, '#f0f8f0'); ctx.fillStyle = gradient; ctx.fillRect(0, 0, canvas.width, canvas.height); // Draw mouse position indicator ctx.fillStyle = 'rgba(35, 79, 30, 0.3)'; ctx.beginPath(); ctx.arc(mouseX, mouseY, 8, 0, Math.PI * 2); ctx.fill(); ctx.strokeStyle = '#234F1E'; ctx.lineWidth = 2; ctx.beginPath(); ctx.arc(mouseX, mouseY, 8, 0, Math.PI * 2); ctx.stroke(); // Draw vector field for (let x = vectorDensity / 2; x < canvas.width; x += vectorDensity) { for (let y = vectorDensity / 2; y < canvas.height; y += vectorDensity) { const vector = calculateVector(x, y, time); drawVector(x, y, vector.vx, vector.vy); } } time += 1; animationId = requestAnimationFrame(animate); } // Event listeners canvas.addEventListener('mousemove', (e) => { const rect = canvas.getBoundingClientRect(); mouseX = e.clientX - rect.left; mouseY = e.clientY - rect.top; }); canvas.addEventListener('mouseleave', () => { mouseX = canvas.width / 2; mouseY = canvas.height / 2; }); strengthSlider.addEventListener('input', (e) => { fieldStrength = parseFloat(e.target.value); strengthValue.textContent = fieldStrength.toFixed(1); }); densitySlider.addEventListener('input', (e) => { vectorDensity = parseInt(e.target.value); densityValue.textContent = vectorDensity; initializeField(); }); resetBtn.addEventListener('click', () => { mouseX = canvas.width / 2; mouseY = canvas.height / 2; time = 0; fieldStrength = 1.0; vectorDensity = 20; strengthSlider.value = 1.0; densitySlider.value = 20; strengthValue.textContent = '1.0'; densityValue.textContent = '20'; initializeField(); }); // Initialize and start animation initializeField(); animate(); // Cleanup on page unload window.addEventListener('beforeunload', () => { if (animationId) { cancelAnimationFrame(animationId); } }); `} height={600} showCode={false} autoResize={false} /> #### Simple Calculator Example

Enter numbers and click Calculate

`} css={` .calculator { display: flex; flex-direction: column; gap: 10px; max-width: 300px; margin: 0 auto; padding: 20px; } .calculator input, .calculator select, .calculator button { padding: 10px; border: 2px solid #234F1E; border-radius: 6px; font-size: 16px; } .calculator button { background: #234F1E; color: white; cursor: pointer; font-weight: bold; } .calculator button:hover { background: #1a3d17; } #result { font-size: 18px; font-weight: bold; color: #234F1E; text-align: center; padding: 15px; background: #f0f8f0; border-radius: 6px; border: 2px solid #e0f0e0; min-height: 20px; } `} javascript={` function calculate() { const num1 = parseFloat(document.getElementById('num1').value); const num2 = parseFloat(document.getElementById('num2').value); const operation = document.getElementById('operation').value; if (isNaN(num1) || isNaN(num2)) { document.getElementById('result').textContent = 'Please enter valid numbers'; return; } let result; switch(operation) { case '+': result = num1 + num2; break; case '-': result = num1 - num2; break; case '*': result = num1 * num2; break; case '/': result = num2 !== 0 ? num1 / num2 : 'Cannot divide by zero'; break; } document.getElementById('result').textContent = 'Result: ' + result; } // Add some interactivity document.addEventListener('DOMContentLoaded', function() { const inputs = document.querySelectorAll('input'); inputs.forEach(input => { input.addEventListener('keypress', function(e) { if (e.key === 'Enter') { calculate(); } }); }); }); `} height={400} showCode={true} autoResize={false} /> ## Best Practices ### 1. Structure Your Content - Use clear headings to organize your content - Keep paragraphs concise and focused - Use lists to break down complex information - Include a table of contents for longer posts ### 2. Optimize for Readability - Write in a conversational tone - Use short sentences and paragraphs - Include plenty of white space - Add relevant images and code examples ### 3. SEO Considerations - Write descriptive titles and excerpts - Use relevant tags consistently - Include alt text for all images - Optimize your front matter SEO fields ### 4. Interactive Elements - Use components to enhance, not replace, good writing - Ensure interactive elements are accessible - Test components on different screen sizes - Keep loading times in mind ### 5. Code Examples - Always specify the language for syntax highlighting - Include complete, runnable examples when possible - Add comments to explain complex code - Use consistent formatting and indentation ## File Naming and Organization ### File Naming Convention Use the format: `YYYY-MM-DD-post-slug.mdx` Examples: - `2025-12-16-mdx-blog-guide.mdx` - `2025-12-15-react-hooks-tutorial.mdx` - `2025-12-14-machine-learning-basics.mdx` ### Directory Structure ``` blog-content/ ├── posts/ │ ├── 2025-12-16-mdx-blog-guide.mdx │ ├── 2025-12-15-react-tutorial.mdx │ └── 2025-12-14-ml-basics.mdx ├── images/ │ ├── post-images/ │ └── thumbnails/ └── README.md ``` ## Publishing Workflow 1. **Create your MDX file** with proper front matter 2. **Write your content** using Markdown and MDX syntax 3. **Add images** to the images directory if needed 4. **Test locally** if you have a development setup 5. **Commit and push** to your blog repository 6. **Wait for deployment** (automatic via ISR) ## Common Pitfalls to Avoid ### 1. Invalid Front Matter ```yaml # ❌ Wrong - missing quotes around date publishedAt: 2025-12-16T21:00:00Z # ✅ Correct - properly quoted publishedAt: "2025-12-16T21:00:00Z" ``` ### 2. Mixing Markdown and JSX Incorrectly ```markdown **Bold text** and JSX **Bold text** and **more bold text** ``` ### 3. Missing Component Imports If you use custom components, make sure they're available in the MDX component library. ### 4. Accessibility Issues Always include: - Alt text for images - Proper heading hierarchy - Descriptive link text - Keyboard navigation support ## Advanced Tips ### 1. Custom Styling You can use Tailwind CSS classes directly in your MDX: ```jsx

Column 1

Content for the first column.

Column 2

Content for the second column.

``` ### 2. Conditional Content You can use JavaScript expressions in MDX: ```jsx {process.env.NODE_ENV === 'development' && (

This content only shows in development mode.

)} ``` ### 3. Dynamic Content ```jsx

This post was last updated: {new Date().toLocaleDateString()}

``` ## Conclusion MDX provides a powerful way to create rich, interactive blog content while maintaining the simplicity of Markdown. By following these guidelines and best practices, you can create engaging posts that provide value to your readers. Remember to: - Start with good content and clear structure - Use interactive elements to enhance, not distract - Optimize for both readers and search engines - Test your posts across different devices and browsers Happy blogging with MDX! 🚀 --- *This guide covers the essentials of writing MDX blog posts. For more advanced topics or specific questions, feel free to explore the documentation or reach out with questions.*