MDX Notes
HubMDX vs Markdown: A Detailed ComparisonWhat is MDX?Why Use MDX? Benefits and Use CasesCreate Your First MDX FileInstalling MDX - Complete Setup GuideMDX Project Structure - Organizing Your Content and ComponentsBlockquotes in MDXCode Blocks in MDXHeadings in MDXImages in MDXLinks in MDXLists in MDXParagraphs in MDXTables in MDXText Formatting in MDXFrontmatter BasicsDocument Metadata in MDXPage Configuration via FrontmatterSEO Fields in FrontmatterBuilding an Accordion/Collapsible ComponentBuilding an Alert/Admonition ComponentBuilding a Card ComponentCreating Custom Components for MDXBuilding a Tabs ComponentInteractive Documentation with MDXMDX LayoutsMDX PluginsPerformance Optimization for MDXReusable Content in MDXSyntax Highlighting in MDXAdmonitions in DocusaurusCode Tabs and CodeBlock in DocusaurusMDX in DocusaurusSidebar Configuration in DocusaurusTabs Component in DocusaurusDocument Versioning in DocusaurusAccessibility in MDXCommon MDX Mistakes and FixesSEO Optimization for MDX ContentMDX Writing Style GuideUsers API - Create UserGetting Started with React in 2024useTheme HookAlex Rivera - Full-Stack Developer & DesignerComplete MDX CheatsheetFurther Reading and MDX ResourcesMDX Interview Questions and AnswersTools for MDX DevelopmentDynamic Content in MDXExporting Variables in MDXImporting Components in MDXJSX Basics in MDXPassing Props in MDXReact Components in MDXMDX Learning RoadmapSetting Up MDX with Next.jsBuilding a Blog with Next.js and MDXCustom Components in Next.js MDXSEO with MDX in Next.js
Make your MDX docs accessible to everyone — semantic HTML, ARIA, keyboard nav, screen readers, color contrast, and WCAG compliance made practical.
If someone can't read your docs, your docs don't exist for them. Accessibility isn't a nice-to-have — it's part of the job.
The good news: MDX gives you both Markdown's semantic defaults and React's component model. Together, they make accessible docs pretty straightforward if you think about it from the start.
Why Accessibility Matters
- 15% of people worldwide have some form of disability
- It's the law in many places (ADA, Section 508, EAA)
- It helps everyone — good accessibility means better UX for all users (try using your site with a broken mouse hand)
- SEO bonus — accessible content is well-structured content, and search engines love structure
Semantic HTML
Markdown already produces semantic HTML. That's a free win. Don't throw it away.
Example
{/* ✅ Markdown generates semantic HTML automatically */}
# Page Title → <h1>
## Section → <h2>
- List item → <ul><li>
1. Ordered item → <ol><li>
**Bold text** → <strong>
*Italic text* → <em>
[Link text](url) → <a href="url">
> Blockquote → <blockquote>
{/* ❌ Don't break semantics with custom components */}
<div className="heading-style">This looks like a heading</div>
{/* ✅ Use proper heading elements */}
## This IS a heading
A <div> styled to look like a heading fools sighted users but leaves screen reader users completely lost.
Semantic Component Design
Example
// ✅ Accessible callout using semantic elements
export function Callout({ type = 'info', title, children }) {
const roleMap = {
warning: 'alert',
error: 'alert',
info: 'note',
success: 'status'
};
return (
<aside
role={roleMap[type]}
aria-label={title || `${type} callout`}
className={`callout callout-${type}`}
>
{title && <strong className="callout-title">{title}</strong>}
<div className="callout-content">{children}</div>
</aside>
);
}
ARIA Labels and Roles
When plain HTML isn't enough to communicate meaning, ARIA fills the gaps:
jsx title="components/CodePlayground.jsx" example
export function CodePlayground({ code, language, title }) {
return (
<div
role="region"
aria-label={`Interactive ${language} code example: ${title}`}
>
<div role="toolbar" aria-label="Code editor controls">
<button aria-label="Copy code to clipboard">
<CopyIcon aria-hidden="true" />
<span className="sr-only">Copy</span>
</button>
<button aria-label="Run code example">
<PlayIcon aria-hidden="true" />
<span className="sr-only">Run</span>
</button>
</div>
<pre role="code" aria-label={`${language} source code`}>
<code>{code}</code>
</pre>
<div
role="log"
aria-label="Code execution output"
aria-live="polite"
>
{/* Output appears here */}
</div>
</div>
);
}ARIA Best Practices
| Rule | Example |
|---|---|
| Use semantic HTML first | <nav> instead of <div role="navigation"> |
| Don't override native semantics | Never put role="button" on a <button> |
| All interactive elements need labels | aria-label or visible text |
| Decorative elements are hidden | aria-hidden="true" on icons with text |
| Live regions announce changes | aria-live="polite" for dynamic updates |
Color Contrast
Your beautiful low-contrast gray-on-slightly-less-gray design? Unreadable for a lot of people. Check your ratios.
jsx title="components/Badge.jsx" example
// ✅ High contrast color combinations
const badgeStyles = {
info: {
backgroundColor: '#dbeafe', // Light blue background
color: '#1e3a5f', // Dark blue text — 7.2:1 ratio
borderColor: '#3b82f6'
},
warning: {
backgroundColor: '#fef3c7', // Light yellow background
color: '#92400e', // Dark amber text — 5.8:1 ratio
borderColor: '#f59e0b'
},
error: {
backgroundColor: '#fee2e2', // Light red background
color: '#991b1b', // Dark red text — 7.1:1 ratio
borderColor: '#ef4444'
}
};
// WCAG requirements:
// - Normal text: 4.5:1 minimum contrast ratio
// - Large text (18px+ or 14px+ bold): 3:1 minimum
// - UI components: 3:1 minimum against adjacent colorsColor Guidelines
- Never use color alone to convey meaning — add icons, text, or patterns too
- Test with colorblindness simulators — 8% of males are colorblind
- Your dark mode needs good contrast too — don't just invert and call it done
- Use tools: WebAIM Contrast Checker, Chrome DevTools accessibility audit
Keyboard Navigation
If you can't tab to it, click it, or escape from it with just a keyboard — it's broken.
Example
export function Tabs({ tabs, activeTab, onChange }) {
const handleKeyDown = (e, index) => {
let newIndex;
switch (e.key) {
case 'ArrowRight':
newIndex = (index + 1) % tabs.length;
break;
case 'ArrowLeft':
newIndex = (index - 1 + tabs.length) % tabs.length;
break;
case 'Home':
newIndex = 0;
break;
case 'End':
newIndex = tabs.length - 1;
break;
default:
return;
}
e.preventDefault();
onChange(newIndex);
// Move focus to the new tab
document.getElementById(`tab-${newIndex}`)?.focus();
};
return (
<div role="tablist" aria-label="Content tabs">
{tabs.map((tab, index) => (
<button
key={tab.id}
id={`tab-${index}`}
role="tab"
aria-selected={index === activeTab}
aria-controls={`panel-${index}`}
tabIndex={index === activeTab ? 0 : -1}
onKeyDown={(e) => handleKeyDown(e, index)}
onClick={() => onChange(index)}
>
{tab.label}
</button>
))}
{tabs.map((tab, index) => (
<div
key={tab.id}
id={`panel-${index}`}
role="tabpanel"
aria-labelledby={`tab-${index}`}
hidden={index !== activeTab}
tabIndex={0}
>
{tab.content}
</div>
))}
</div>
);
}
Keyboard Navigation Requirements
- Tab: Move between focusable elements
- Enter/Space: Activate buttons and links
- Arrow keys: Navigate within widget groups (tabs, menus)
- Escape: Close modals, dismiss popups
- Visible focus indicator: Always show where focus is
Screen Reader Compatibility
Screen readers read your page linearly. Write content that makes sense when read aloud, in order.
Example
{/* ✅ Screen reader friendly content */}
{/* Links have descriptive text */}
Read the [MDX compilation guide](/guides/compilation) for details.
{/* Images have meaningful alt text */}
{/* Tables have proper headers */}
| Feature | Markdown | MDX |
|---------|----------|-----|
| Headings | ✅ | ✅ |
| Components | ❌ | ✅ |
| Expressions | ❌ | ✅ |
{/* Abbreviations are expanded */}
<abbr title="Web Content Accessibility Guidelines">WCAG</abbr>
{/* Skip navigation for long pages */}
<a href="#main-content" className="skip-link">
Skip to main content
</a>
Screen Reader Tips
- Announce dynamic changes with
aria-liveregions - Hide decorative content with
aria-hidden="true" - Use visually-hidden text for additional context (
.sr-onlyclass) - Test with actual screen readers: NVDA (Windows), VoiceOver (macOS), JAWS
Alt Text for Images
Don't write "image of..." — the screen reader already says "image." Describe what it *shows*.
Example
{/* ✅ Descriptive alt text examples */}
{/* Informative images — describe content and purpose */}
{/* Functional images — describe the action */}
{/* Complex images — provide brief alt + detailed description */}
<details>
<summary>Detailed description of the architecture diagram</summary>
The diagram shows three layers: the source layer contains .mdx files,
the processing layer includes the remark and rehype plugin pipelines,
and the output layer produces React components that render to HTML.
</details>
{/* Decorative images — empty alt text */}
Focus Management
When content changes dynamically (modals opening, tabs switching), focus needs to follow:
Example
import { useEffect, useRef } from 'react';
export function Modal({ isOpen, onClose, title, children }) {
const closeRef = useRef(null);
const previousFocus = useRef(null);
useEffect(() => {
if (isOpen) {
// Store current focus to restore later
previousFocus.current = document.activeElement;
// Move focus into the modal
closeRef.current?.focus();
} else if (previousFocus.current) {
// Restore focus when modal closes
previousFocus.current.focus();
}
}, [isOpen]);
if (!isOpen) return null;
return (
<div
role="dialog"
aria-modal="true"
aria-labelledby="modal-title"
onKeyDown={(e) => e.key === 'Escape' && onClose()}
>
<h2 id="modal-title">{title}</h2>
<button ref={closeRef} onClick={onClose} aria-label="Close dialog">
×
</button>
<div>{children}</div>
</div>
);
}
Accessible MDX Components Library
Build a small library of accessible components and reuse them everywhere:
jsx title="components/accessible/index.js" example
export { Callout } from './Callout'; // role="note" or role="alert"
export { Tabs } from './Tabs'; // Full keyboard + ARIA tabs
export { Accordion } from './Accordion'; // Expandable sections
export { Modal } from './Modal'; // Focus trap + escape handling
export { CodeBlock } from './CodeBlock'; // Labeled code regions
export { SkipLink } from './SkipLink'; // Skip navigation
export { VisuallyHidden } from './Hidden'; // Screen reader only textWCAG Guidelines Compliance
Target WCAG 2.1 Level AA as your minimum. Here's the framework:
The Four Principles (POUR)
- Perceivable — Content can be perceived by all senses
- Operable — Interface works with all input methods
- Understandable — Content and UI behavior make sense
- Solid — Content works with current and future tech
Key Success Criteria
| Criterion | Level | What it means for MDX |
|---|---|---|
| 1.1.1 Non-text Content | A | Alt text on all images |
| 1.3.1 Info and Relationships | A | Semantic HTML from Markdown |
| 1.4.3 Contrast (Minimum) | AA | 4.5:1 for text in components |
| 2.1.1 Keyboard | A | All components keyboard-operable |
| 2.4.6 Headings and Labels | AA | Descriptive heading hierarchy |
| 3.1.1 Language of Page | A | lang attribute on <html> |
| 4.1.2 Name, Role, Value | A | ARIA on custom components |
Testing Tools
Don't guess — test.
bash example
# Automated testing
npm install --save-dev axe-core @axe-core/react jest-axe
# Linting
npm install --save-dev eslint-plugin-jsx-a11yExample
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
import { Callout } from '../components/Callout';
expect.extend(toHaveNoViolations);
test('Callout component has no accessibility violations', async () => {
const { container } = render(
<Callout type="warning" title="Caution">
This is a warning message.
</Callout>
);
const results = await axe(container);
expect(results).toHaveNoViolations();
});
Recommended Testing Tools
- axe DevTools — Browser extension for automated audits
- Lighthouse — Built into Chrome DevTools
- WAVE — Web accessibility evaluation tool
- NVDA/VoiceOver — Real screen reader testing (automated tools catch ~30% of issues; real testing catches the rest)
- Stark — Figma/browser contrast checking
- jest-axe — Automated testing in CI/CD
Summary
Accessibility isn't extra work bolted on at the end. It's a quality bar. Markdown gives you semantic HTML for free. Build your custom components with ARIA and keyboard support from day one. Test with real screen readers, not just automated tools. And target WCAG 2.1 AA — your future self navigating with a broken trackpad will thank you.
Exam Focus
Revise definitions, diagrams, examples, and short-answer points for Accessibility in MDX.
Interview Use
Prepare one clear explanation, one practical example, and one common mistake for this MDX Tutorial topic.
Search Terms
mdx-tutorial, mdx tutorial, mdx, tutorial, best, practices, accessibility, accessibility in mdx
Related MDX Tutorial Topics
Continue learning this concept
Best PracticesCommon MDX Mistakes and FixesThe MDX errors youBest PracticesSEO Optimization for MDX ContentHow to make your MDX docs show up in search results — keywords, meta tags, headings, internal links, and technical SEO that actually works.Best PracticesMDX Writing Style GuideHow to write MDX docs that are consistent, readable, and donAdvancedInteractive Documentation with MDXMake your docs do things. Live code playgrounds, editable examples, quizzes, step-by-step tutorials — all built with React components inside MDX.AdvancedMDX LayoutsWrap your MDX pages in consistent shells — headers, sidebars, footers. Learn how to build, nest, and conditionally swap layouts based on frontmatter.AdvancedMDX PluginsAdd superpowers to your MDX with remark and rehype plugins — tables, math, syntax highlighting, auto-linked headings. Plus how to write your own.