Markdown and MDX pages in Astro

Introduction

Markdown and MDX pages let you write content easily with simple text and add interactive components when needed.

You want to write blog posts or articles quickly without complex code.

You need to mix text content with interactive UI components.

You want to keep your content and design separate but still connected.

You want to use simple formatting like headings, lists, and links.

You want to create documentation with live examples.

Syntax

Astro

---
title: "My Page Title"
date: 2024-06-01
---

# Heading

This is a paragraph in Markdown.

<ComponentName someProp="value" />

Markdown uses simple symbols like # for headings and * for lists.

MDX lets you add components inside Markdown by writing them as JSX tags.

Examples

This is a basic Markdown page with a title and a heading.

Astro

---
title: "Simple Markdown"
---

# Hello World

This is a simple Markdown page.

This MDX page includes a React-like component called Button inside the Markdown.

Astro

---
title: "MDX Example"
---

# Welcome

Here is a button:

<Button>Click me</Button>

Frontmatter at the top stores metadata like title and date for the page.

Astro

---
title: "Using Frontmatter"
date: 2024-06-01
---

## Post Date

The post was written on 2024-06-01.

Sample Program

This MDX page shows a heading, some text, and a custom button component imported from another file.

Astro

---
title: "My First MDX Page"
---

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

# Greetings

Welcome to my page.

<MyButton label="Press me" />

Important Notes

Always include frontmatter at the top to add metadata like title or date.

MDX pages can import and use components just like regular Astro components.

Use Markdown for simple text and MDX when you want interactive parts.

Summary

Markdown lets you write formatted text easily.

MDX adds the power to include components inside Markdown.

Astro supports both for flexible content creation.

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