MDX Cheatsheet

📘 MDX Cheatsheet

MDX lets you write JSX inside Markdown files — combining documentation and interactivity.

📝 Basic Markdown Syntax

Headers

# H1
## H2
### H3
#### H4
##### H5
###### H6

Emphasis

*Italic* or _Italic_
**Bold** or __Bold__
~~Strikethrough~~

Lists

- Unordered list item
* Another item
+ Another item
 
1. Ordered list item
2. Another item

Code Blocks

function greet(name) {
  return `Hello, ${name}`;
}

Inline: `const x = 10`

Blockquotes

> This is a quote.

Horizontal Rule

---

Links & Images

[Link Text](https://example.com)
 
![Alt Text](https://example.com/image.jpg)

🚀 JSX in MDX

Embedding Components

import MyComponent from './MyComponent'
 
<MyComponent prop="value" />

Using Props

export const meta = {
  title: "My Page",
  description: "With custom metadata",
}

Dynamic JSX

{true && <strong>This is shown!</strong>}

🔌 Custom Components

Component Shortcodes

<MyAlert type="warning">
  Be careful!
</MyAlert>

Wrapper Component

export const layout = ({ children }) => (
  <Layout>{children}</Layout>
)

🎨 Styling in MDX

Inline styles

<p style={{ color: 'tomato', fontWeight: 'bold' }}>Styled Text</p>

Tailwind + MDX (if supported)

<div className="bg-blue-100 p-4 rounded-lg">
  Tailwind-styled box
</div>

📚 Syntax Highlighting

const Button = () => <button>Click me</button>;

🧩 MDX Layouts

Page Layouts

---
layout: ../layouts/DocsLayout.astro
title: "Using Layouts"
---
 
# Layout Example

Wrapping with `<MDXProvider />`

import { MDXProvider } from '@mdx-js/react'
import { CodeBlock, Note } from './components'
 
const components = { pre: CodeBlock, Note }
 
<MDXProvider components={components}>
  <App />
</MDXProvider>

🛠️ Plugins & Configuration

Common MDX Plugins

@mdx-js/mdx
@mdx-js/react
remark-gfm (tables, strikethrough)
remark-slug (headings with anchors)
rehype-autolink-headings
remark-code-titles

Example: `next.config.js` with MDX

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/
})
module.exports = withMDX({
  pageExtensions: ['js', 'jsx', 'md', 'mdx'],
})

🧪 Interactive Examples

State in JSX

import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>Clicked {count} times</button>
}
 
<Counter />

📊 Tables

| Syntax | Description |
|--------|-------------|
| Header | Title       |
| Cell   | Content     |

📦 Using Frontmatter

---
title: "Hello MDX"
description: "MDX frontmatter example"
date: 2025-05-27
---

🧠 Tips and Best Practices

Keep components reusable and small.
Separate presentation components from logic.
Use remark/rehype plugins for cleaner Markdown.
Validate MDX files with linters or custom scripts.

🧱 Useful Packages

@mdx-js/react
@mdx-js/loader
next-mdx-remote
mdx-bundler
remark-mdx
astro-mdx
vite-plugin-mdx

🗂️ Directory Structure Example

src/
  components/
    CodeBlock.js
    Alert.js
  pages/
    docs/
      intro.mdx
      api.mdx
  layouts/
    DocsLayout.jsx

🔍 Searchable Content Tips

Add IDs to headings:
```
## Getting Started {#getting-started}
```
Use remark-slug to auto-generate anchors.

🔄 Hybrid Rendering (for frameworks like Next.js)

// pages/docs/[slug].js
import { getMdxPage } from '../../lib/mdx'
 
export default function DocPage({ code, frontmatter }) {
  return <MDXRemote {...code} />
}

⛓️ MDX with Content Collections

import content from '../content/docs/*.mdx'
 
export async function getStaticProps() {
  const docs = await loadContent('docs')
  return { props: { docs } }
}

🧹 Linting + Formatting

`.prettierrc`

{
  "plugins": ["prettier-plugin-mdx"],
  "semi": false,
  "singleQuote": true
}

`.eslintrc`

{
  "extends": ["next", "plugin:@mdx-js/recommended"]
}