Markdown and MDX pages in Astro - Mini Project: Build & Apply

Markdown and MDX pages

📖 Scenario: You are building a simple Astro website that uses Markdown and MDX pages to show content. Markdown (.md) files are great for plain text with formatting, and MDX (.mdx) files let you add React components inside your Markdown.This project will guide you to create a Markdown page, then add an MDX page with a React component, and finally configure Astro to render them.

🎯 Goal: Build an Astro project with one Markdown page and one MDX page that includes a React component. You will see how Astro renders both types of pages seamlessly.

📋 What You'll Learn

Create a Markdown file with a title and paragraph

Create a React component in a separate file

Create an MDX file that uses the React component

Configure Astro to render Markdown and MDX pages

💡 Why This Matters

🌍 Real World

Many websites use Markdown for content pages and MDX to add interactive React components inside content. Astro supports both smoothly.

💼 Career

Knowing how to work with Markdown, MDX, and React in Astro is useful for frontend developers building modern static and dynamic websites.

1

Create a Markdown page

Create a Markdown file named src/pages/about.md with a top-level heading # About Us and a paragraph Welcome to our Astro site!

Astro

# Create src/pages/about.md with a heading and paragraph
# Your code here

Hint

Markdown headings start with #. Paragraphs are plain text below headings.

2

Create a React component

Create a React component named Greeting.jsx inside src/components/ that returns a <p> element with text Hello from React!

Astro

// Create src/components/Greeting.jsx with a React component
// Your code here

Hint

Use export default function Greeting() { return <p>Hello from React!</p>; }

3

Create an MDX page using the React component

Create an MDX file named src/pages/welcome.mdx. Import the Greeting component from ../components/Greeting.jsx. Add a heading # Welcome and include the <Greeting /> component below it.

Astro

---

# Create src/pages/welcome.mdx with a heading and Greeting component
# Your code here

Hint

MDX files can import React components and use them like JSX tags.

4

Configure Astro to support React and MDX

In astro.config.mjs, import react from @astrojs/react and mdx from @astrojs/mdx and add both to the integrations array in the exported config object.

Astro

// Edit astro.config.mjs to import react and mdx and add them to integrations
// Your code here

Hint

Use import react from '@astrojs/react' and import mdx from '@astrojs/mdx' and add react() and mdx() to integrations.

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