Markdown and MDX pages in Astro - Performance & Optimization

Performance: Markdown and MDX pages

MEDIUM IMPACT

This affects page load speed and rendering performance by how content is parsed and hydrated in the browser.

Rendering static content with interactive components

Astro

---
title: Static Page
---

This is static text.

<!-- Use Astro components for interactivity only where needed -->

import MyComponent from '../components/MyComponent.astro';

<MyComponent client:load />

Markdown content is rendered to static HTML at build time, reducing JS bundle size and improving load speed; interactive components load only when needed.

📈 Performance Gainsaves 50-100kb JS, reduces blocking time by 100-200ms, improves LCP

Rendering static content with interactive components

Astro

import MyComponent from '../components/MyComponent.jsx';

export default function Page() {
  return (
    <MDXContent>
      <MyComponent />
      <p>This is static text.</p>
    </MDXContent>
  );
}

MDX pages hydrate all React components on the client, increasing JavaScript bundle size and delaying Largest Contentful Paint.

📉 Performance Costadds 50-100kb to JS bundle, blocks rendering for 100-200ms on slow devices

Performance Comparison

Pattern	DOM Operations	Reflows	Paint Cost	Verdict
Static Markdown	Minimal DOM nodes, static HTML	0 reflows on load	Fast paint with static content	[OK] Good
MDX with many React components	More DOM nodes, dynamic React tree	Multiple reflows during hydration	Slower paint due to JS execution	[X] Bad

Rendering Pipeline

Markdown content is converted to static HTML during build, so the browser renders it immediately without extra JavaScript. MDX content requires hydration of React components, which delays rendering and increases JavaScript parsing and execution.

→HTML Parsing

→JavaScript Parsing

→Hydration

→Paint

⚠️ BottleneckHydration stage due to JavaScript execution for MDX components

Core Web Vital Affected

LCP

This affects page load speed and rendering performance by how content is parsed and hydrated in the browser.

Optimization Tips

1Prefer static Markdown for mostly static content to reduce JavaScript and improve LCP.

2Use MDX only when interactive React components are necessary, and keep them minimal.

3Defer hydration of interactive components with client directives to avoid blocking rendering.

Performance Quiz - 3 Questions

Which content type generally results in faster initial page load in Astro?

A Static Markdown pages

B MDX pages with many React components

C Pages with client-side rendered JavaScript only

D Pages using server-side rendering with heavy APIs

DevTools: Performance

How to check: Record a page load in the Performance panel, then look for long scripting tasks and hydration markers.

What to look for: Look for long 'Evaluate Script' and 'Hydrate' tasks that delay Largest Contentful Paint.

Practice

1. What is the main difference between Markdown and MDX in Astro?

easy

A. Markdown supports JavaScript code, but MDX does not.

B. Markdown files can run server code, MDX files cannot.

C. MDX is only for styling, Markdown is for content.

D. MDX allows embedding components inside Markdown content, while Markdown does not.

Solution

1. Step 1: Understand Markdown basics

   Markdown is a simple way to write formatted text like headings, lists, and links.

2. Step 2: Understand MDX extension

   MDX extends Markdown by allowing you to include interactive components inside the text.

3. Final Answer:

   MDX allows embedding components inside Markdown content, while Markdown does not. -> Option D

4. Quick Check:

   MDX = Markdown + components [OK]

Hint: Remember: MDX = Markdown + components [OK]

Common Mistakes:

• Thinking Markdown supports components
• Confusing MDX with styling only
• Believing Markdown runs server code

2. Which file extension should you use for a page that includes React components inside Markdown in Astro?

easy

A. .mdx

B. .astro

C. .md

D. .jsx

Solution

1. Step 1: Identify file types for Markdown and MDX

   Markdown files use .md extension, MDX files use .mdx extension to support components.

2. Step 2: Match file extension to React components inside Markdown

   To include React components inside Markdown, use .mdx files.

3. Final Answer:

   .mdx -> Option A

4. Quick Check:

   React components in Markdown = .mdx [OK]

Hint: Use .mdx for Markdown with components [OK]

Common Mistakes:

• Using .md for MDX content
• Confusing .astro with Markdown files
• Choosing .jsx which is for pure React files

3. Given this Astro MDX page snippet, what will be rendered?

---
import Button from '../components/Button.jsx';
---
# Welcome
Click me

medium

A. A syntax error because components can't be imported in MDX.

B. Only the heading 'Welcome' without the button.

C. A heading 'Welcome' and a clickable button labeled 'Click me'.

D. The button renders but the heading does not.

Solution

1. Step 1: Understand MDX import and usage

   MDX allows importing components at the top and using them inline in the Markdown content.

2. Step 2: Analyze the snippet output

   The heading '# Welcome' renders as a heading, and the <Button> component renders as a clickable button with text 'Click me'.

3. Final Answer:

   A heading 'Welcome' and a clickable button labeled 'Click me'. -> Option C

4. Quick Check:

   MDX imports + components = rendered output [OK]

Hint: MDX imports components, renders both text and UI [OK]

Common Mistakes:

• Thinking imports cause syntax errors in MDX
• Assuming components won't render inside MDX
• Ignoring Markdown headings when components are present

4. What is wrong with this Astro MDX page snippet?

---
import Alert from '../components/Alert.jsx'
---
# Notice
This is important

medium

A. No error; this code is correct.

B. Incorrect import path syntax.

C. Missing semicolon after import statement.

D. Missing closing quote in import statement.

Solution

1. Step 1: Check import syntax in MDX frontmatter

   In MDX frontmatter, semicolons are optional and import paths use quotes correctly.

2. Step 2: Verify component usage

   The Alert component is imported and used correctly inside the MDX content.

3. Final Answer:

   No error; this code is correct. -> Option A

4. Quick Check:

   MDX import syntax is flexible = correct [OK]

Hint: Semicolons optional in MDX imports [OK]

Common Mistakes:

• Expecting semicolons after imports
• Thinking import paths need special syntax
• Assuming missing semicolon causes error

5. You want to create a blog post in Astro that uses Markdown for text and includes a custom interactive component for comments. Which approach is best?

hard

A. Write the entire post in .md and import the component inside it.

B. Use .mdx for the post so you can embed the comment component directly.

C. Create a .astro page and write Markdown inside it manually.

D. Use .md and add the component via client-side JavaScript after page load.

Solution

1. Step 1: Understand Markdown limitations

   Plain .md files cannot embed components directly; they are static content.

2. Step 2: Consider MDX advantages

   .mdx files allow mixing Markdown with components, perfect for interactive elements like comments.

3. Step 3: Evaluate other options

   .astro pages can include Markdown but require more setup; client-side JS injection is less clean and less integrated.

4. Final Answer:

   Use .mdx for the post so you can embed the comment component directly. -> Option B

5. Quick Check:

   Interactive + Markdown = MDX [OK]

Hint: Embed components directly by using .mdx files [OK]

Common Mistakes:

• Trying to import components in plain .md files
• Ignoring MDX for interactive content
• Overcomplicating with client-side JS injection