MDX Content and Components

Level: Beginner

ℹ️ What You'll Learn

• Writing MDX files with Markdown syntax
• Importing and using React components
• Code blocks with language highlighting
• Callout components (Info, Warning, Tip)
• Tables, lists, and rich formatting
• Creating custom interactive components
• Embedding examples and demos
• SMS API documentation with MDX

Why This Matters

MDX lets you write Markdown with React components. Regular Markdown limits formatting. MDX adds interactivity and rich content without leaving Markdown files.

What is MDX?

MDX = Markdown with JSX (React syntax).

Write Markdown like normal. Add React components where needed.

# My Article

Regular markdown text.

<MyCustomComponent prop="value" />

More markdown.

Docusaurus processes MDX → React → HTML.

Basic MDX Syntax

# Heading

**Bold**, *italic*, `code`

- Bullet points
- Still markdown

## Custom Component

<MyComponent title="Hello" />

Back to markdown.

Mix Markdown and React freely.

Frontmatter (Metadata)

Every .mdx file starts with frontmatter:

---
title: "Article Title"
description: "SEO description"
sidebar_position: 1
---

Content here.

Available fields:

• title — Page title and sidebar label
• description — Meta description (SEO)
• sidebar_position — Order in sidebar
• hide_table_of_contents — Hide TOC
• keywords — SEO keywords
• image — Featured image

Built-in Docusaurus Components

import { Tip, Info, Warning, Danger } from '@site/src/components/Callout';

<Tip title="Pro Tip">
Content here. Background color = green.
</Tip>

<Info title="Information">
Content here. Background color = blue.
</Info>

<Warning title="Caution">
Content here. Background color = amber.
</Warning>

<Danger title="Danger">
Content here. Background color = red.
</Danger>

These = styled boxes for callouts. Used throughout NexCoding.

Code Blocks

\`\`\`csharp
// Code block with language
public class Student {
  public string Name { get; set; }
}
\`\`\`

\`\`\`csharp title="Student.cs"
// Code with title
public class Student { }
\`\`\`

\`\`\`csharp {2-4}
// Highlight lines 2-4
public class Student {
  public string Name { get; set; }
  public int RollNumber { get; set; }
}
\`\`\`

Syntax highlighting automatic. Add title= for file name.

Links and Images

# Links
[Link text](https://example.com)
[Internal link](../other-article)
[Link to doc](./01-setup)

# Images
![Alt text](/img/screenshot.png)
![Student data](/img/student-table.webp)

Images go in static/img/ folder.

Tables

| Field | Type | Required |
|-------|------|----------|
| name | string | Yes |
| email | string | Yes |
| className | string | No |

Markdown tables. Docusaurus styles automatically.

SMS Documentation Example

---
title: "Student API"
description: "Get, create, update, delete students"
sidebar_position: 1
---

import { Tip, Warning } from '@site/src/components/Callout';

# Student API Endpoints

API for managing student records in School Management System.

## Base URL

\`\`\`
GET /api/students
\`\`\`

## Get All Students

Retrieve list of all students.

\`\`\`bash
curl -X GET https://api.nexcoding.in/api/students
\`\`\`

**Response:**

\`\`\`json
[
  {
    "id": 101,
    "name": "Ravi Kumar",
    "rollNumber": "101",
    "className": "10-A",
    "email": "ravi@school.in"
  }
]
\`\`\`

<Tip title="Pagination">
Add `?skip=0&take=10` for pagination.
</Tip>

## Create Student

\`\`\`bash
curl -X POST https://api.nexcoding.in/api/students \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "Priya Sharma",
    "rollNumber": "102",
    "className": "10-A",
    "email": "priya@school.in"
  }'
\`\`\`

<Warning title="Validation">
Name and email required. Email must be unique.
</Warning>

| Field | Type | Rules |
|-------|------|-------|
| name | string | Required, max 100 chars |
| rollNumber | string | Required, unique |
| email | string | Required, valid email |
| className | string | Required |

Custom Components

Create reusable components:

// src/components/StudentExample.tsx
export default function StudentExample() {
  return (
    <div style={{ padding: '10px', border: '1px solid #ccc' }}>
      <h3>Student Example</h3>
      <p>Name: Ravi Kumar</p>
      <p>Roll: 101</p>
    </div>
  );
}

Use in MDX:

import StudentExample from '@site/src/components/StudentExample';

# Using Custom Component

<StudentExample />

Tabs (Multiple Versions)

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="js" label="JavaScript">
    \`\`\`javascript
    fetch('/api/students')
      .then(r => r.json())
    \`\`\`
  </TabItem>
  <TabItem value="csharp" label="C#">
    \`\`\`csharp
    var students = await client.GetAsync("/api/students");
    \`\`\`
  </TabItem>
</Tabs>

Show code in multiple languages/frameworks.

Key Takeaways

• MDX = Markdown + React components
• Frontmatter = article metadata
• Built-in callouts (Tip, Info, Warning, Danger)
• Code blocks with syntax highlighting
• Custom React components in Markdown
• Tables, links, images in standard Markdown
• Perfect for API docs and tutorials

💡 Backend Developer Tip

MDX combines best of both worlds. Write Markdown (simple, readable), but add React components when you need interactivity. Great for API documentation that needs code examples in multiple languages.

⚠️ MDX Gotchas

1. JSX syntax strict — Unclosed tags break parsing
2. Indentation matters — In components and code blocks
3. Import at top — Component imports must be at file top
4. Props as strings — Numbers/objects need braces: {5} not 5

🤖Use AI to Learn Faster

Use ChatGPT, Claude, or Copilot to go deeper on MDX Content. Try these prompts:

• "How do you embed React components in Markdown?"
• "What's difference between MDX and Markdown?"
• "How do you create code examples in multiple languages?"
• "Quiz me on MDX syntax"

💡 Tip: After reading this article, paste your own code into AI and ask "What could go wrong here and why?" — fastest way to find edge cases and deepen understanding.