Code Blocks in MDX

If you're writing technical docs, code blocks are probably 50% of your content. MDX handles everything from a quick inline snippet to full interactive editors where readers can modify and run code.

Here's every technique you'll need.

Inline Code

Wrap something in single backticks to make it look like code within a sentence:

Use the useState hook to manage component state.

When to Use Inline Code

Use it for anything that's "code" in the middle of regular text:

• Function names: useState, useEffect
• Variable names: isLoading, userData
• File names: package.json, tsconfig.json
• Terminal commands: npm run build
• CSS properties: display: flex
• HTML elements: <div>, <section>
• Keyboard shortcuts in technical context: Ctrl+C

Backticks Inside Inline Code

If your code itself contains a backtick, wrap it in double backticks with spaces:

Custom Inline Code Styling

You can override how inline code renders:

Fenced Code Blocks

For multi-line code, use triple backticks:

function hello() { console.log('Hello, World!') }

That gives you a preformatted block with monospace font.

Alternative: Tilde Fence

Tildes (~~~) work too, if you prefer:

Language Specification

Add the language name right after the opening fence. This turns on syntax highlighting:

function greet(name) { return Hello, ${name}! }

Common Language Identifiers

Here are the ones you'll use most:

const x = 42

const x: number = 42

function App() { return <div>Hello</div> }

function App(): JSX.Element { return <div>Hello</div> }

def greet(name): return f"Hello, {name}"

npm install @mdx-js/react

.container { display: flex; gap: 1rem; }

<div class="container"> <p>Hello World</p> </div>

{ "name": "my-project", "version": "1.0.0" }

name: Build on: push: branches: [main]

SELECT users.name, orders.total FROM users INNER JOIN orders ON users.id = orders.user_id WHERE orders.total > 100;

Title

• List item
• Another item

import { Button } from './Button'

Hello

Click me

Line Highlighting

Want to draw attention to specific lines? Add line numbers in curly braces after the language:

import React from 'react'

// This line is highlighted function Counter() { const [count, setCount] = React.useState(0)

// These lines are highlighted const increment = () => { setCount(prev => prev + 1) }

return <button onClick={increment}>{count}</button> }

Different Highlighting Syntax

Depending on your setup, you might use different approaches:

const normal = true // highlight-next-line const highlighted = true const alsoNormal = true

// highlight-start const a = 1 const b = 2 const c = 3 // highlight-end

Addition and Deletion Highlighting

function App() { return ( <OldComponent /> <NewComponent /> ) }

Line Numbers

Show line numbers next to code:

function fibonacci(n) { if (n <= 1) return n return fibonacci(n - 1) + fibonacci(n - 2) }

console.log(fibonacci(10))

// This continues from line 15 const result = processData(input) return result.map(item => item.value) }

Line Numbers + Highlighting Together

import { useState } from 'react'

function useToggle(initial = false) { const [value, setValue] = useState(initial) const toggle = () => setValue(v => !v) return [value, toggle] as const }

File Names / Titles

Tell readers which file this code goes in. Use title= in the meta string:

export function Button({ children, onClick }) { return ( <button className="btn" onClick={onClick}> {children} </button> ) }

{ "name": "my-mdx-project", "dependencies": { "@mdx-js/react": "^3.0.0", "next": "^14.0.0" } }

npm create next-app@latest my-project cd my-project npm run dev

File Tab Component

When you need to show multiple related files together:

export function Button({ children }) { return <button className="btn">{children}</button> } ``` </CodeTabs.Tab> <CodeTabs.Tab title="Button.module.css">

export { Button } from './Button'

Copy Button

Readers want to copy your code. Make it easy. Here's a component approach:

Component-Based Approach

Implementation

Make Every Code Block Copyable Automatically

Override the pre element so all fenced code blocks get a copy button without any extra work:

Now every fenced code block in your MDX gets a copy button. No changes to existing content needed.

Live Code Editors

This is where MDX really shines. You can let readers edit code and see results instantly.

Using react-live

Custom Playground Component

Sandpack (by CodeSandbox)

If you want a full mini-IDE embedded in your page:

When to Use Live Editors

• Component documentation — let people tweak props and see what happens
• Tutorials — learning by doing beats reading
• API exploration tools
• Design system playgrounds

Diff Syntax

Show what changed between two versions of code:

• const oldVariable = 'deprecated'

+ const newVariable = 'modern'

function processData(input) {

• return legacyTransform(input)

+ return modernTransform(input, { validate: true }) }

Styled Diff Block

You can combine diff with a title to show migration steps:

import React from 'react'

• import { render } from 'react-dom'

+ import { createRoot } from 'react-dom/client'

function App() { return <div>Hello</div> }

• render(<App />, document.getElementById('root'))

+ const root = createRoot(document.getElementById('root')) + root.render(<App />)

Diff Component

Combining Multiple Features

You can stack these features together. Here's a code block with a file path, line numbers, highlighting, and syntax coloring all at once:

import { useState, useEffect } from 'react'

export function useDebounce<T>(value: T, delay: number): T { const [debouncedValue, setDebouncedValue] = useState<T>(value)

useEffect(() => { const timer = setTimeout(() => setDebouncedValue(value), delay) return () => clearTimeout(timer) }, [value, delay])

return debouncedValue }

Code Groups / Tabs

Show the same thing in multiple package managers or languages:

npm install @mdx-js/react

yarn add @mdx-js/react

pnpm add @mdx-js/react

Best Practices

1. Always specify the language — Without it, there's no syntax highlighting.
2. One concept per block — Don't dump 200 lines with no explanation.
3. Use real names — userName, not foo. fetchOrders(), not doThing().
4. Highlight what matters — Guide the reader's eye to the important lines.
5. Include file names — People need to know where code goes.
6. Add copy buttons — Readers will copy-paste. Make it easy.
7. Test your examples — Broken code kills your credibility instantly.
8. Use diff for changes — Way clearer than writing "now change line 5 to..."
9. Indent consistently — 2 spaces for JS/TS is standard.

Common Mistakes

Wrong Language Identifier

function App() { return <div /> }

function App() { return <div /> }

Content on the Same Line as the Fence

const y = 2

const x = 1 const y = 2

Forgetting to Close the Fence

function broken() { // oops, no closing fence

{/* ✅ GOOD — Always close your fences */}

{/* ❌ BAD — Inconsistent indentation */}

{/* ✅ GOOD — Consistent indentation */}

{/* ❌ BAD — 100+ lines with no explanation */}

{/* ✅ GOOD — Break into focused chunks with explanation */}

Then implement the interface: