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
How to define and use metadata fields in MDX — titles, descriptions, authors, dates, tags, and custom fields that power your content system.
Understanding Document Metadata
Metadata is "data about data." It's the structured info that describes, classifies, and gives context to your document — without being part of the main content itself.
In MDX, metadata lives in frontmatter and does a lot of heavy lifting: powering navigation, enabling search, generating feeds, building SEO tags, and driving template logic.
When your metadata is well-structured, a collection of MDX files becomes a queryable content system. Your framework can automatically generate blog indexes, documentation sidebars, RSS feeds, and sitemaps — all from frontmatter.
yaml example
Title Metadata
The title is the single most important piece of metadata. It shows up everywhere — browser tabs, search results, social shares, nav menus, content lists. Different contexts might need different versions of it.
yaml example
---
# Primary title - displayed as the page heading
title: "Understanding TypeScript Generics"
# Short title for navigation and breadcrumbs
shortTitle: "Generics"
# Subtitle for additional context
subtitle: "From Basic Constraints to Advanced Patterns"
# Navigation label (used in sidebars)
sidebar_label: "TypeScript Generics"
# Browser tab title (if different from main title)
browserTitle: "TypeScript Generics Guide | DevDocs"
---Framework-Specific Title Handling
Next.js (App Router with generateMetadata):
Example
// app/blog/[slug]/page.tsx
import { Metadata } from 'next';
export async function generateMetadata({ params }): Promise<Metadata> {
const post = await getPost(params.slug);
return {
title: post.frontmatter.title,
description: post.frontmatter.description,
openGraph: {
title: post.frontmatter.title,
description: post.frontmatter.description,
},
};
}
Docusaurus:
yaml example
---
title: Understanding TypeScript Generics
sidebar_label: Generics
# Docusaurus automatically uses title for SEO and browser tab
---Description Metadata
The description is a concise summary of what your page is about. It powers SEO meta tags, social media previews, content cards, and search result snippets.
yaml example
---
# Primary description (aim for 150-160 characters for SEO)
description: "Master TypeScript generics with practical examples covering constraints, conditional types, mapped types, and real-world patterns."
# Extended description for content listings
excerpt: "TypeScript generics are one of the most powerful features of the type system. In this guide, we'll explore how generics enable you to write flexible, reusable code while maintaining full type safety."
# One-line summary for compact views
summary: "A complete guide to TypeScript generics"
---Tips for Good Descriptions
- Keep the primary description under 160 characters (that's the SEO sweet spot)
- Include your primary keywords naturally — don't stuff them
- Make it compelling. This is often the first text people see before clicking
- Don't just repeat the title word-for-word
- Use
excerptfor longer summaries in blog listing pages
Author Information
Author metadata can be as simple as a name or as detailed as a full bio with social links. Match it to what your site actually displays.
yaml example
---
# Simple format
author: "Marcus Johnson"
# Detailed format
author:
name: "Marcus Johnson"
email: "marcus@techblog.dev"
url: "https://marcusjohnson.dev"
avatar: "/images/authors/marcus.jpg"
bio: "Senior Frontend Engineer at TechCorp. React enthusiast and OSS contributor."
twitter: "@marcusdev"
github: "marcusj"
# Multiple authors
authors:
- name: "Marcus Johnson"
role: "Primary Author"
avatar: "/images/authors/marcus.jpg"
- name: "Lisa Park"
role: "Technical Reviewer"
avatar: "/images/authors/lisa.jpg"
- name: "Dev Team"
role: "Contributors"
---Using Author Data in Components
jsx example
// components/AuthorCard.jsx
export function AuthorCard({ author }) {
return (
<div className="author-card">
<img src={author.avatar} alt={author.name} />
<div>
<h3>{author.name}</h3>
<p>{author.bio}</p>
<div className="author-links">
{author.twitter && (
<a href={`https://twitter.com/${author.twitter}`}>Twitter</a>
)}
{author.github && (
<a href={`https://github.com/${author.github}`}>GitHub</a>
)}
</div>
</div>
</div>
);
}Date Metadata
Dates track the lifecycle of your content. Different date fields serve different purposes.
yaml example
---
# When the document was first created (internal tracking)
createdAt: 2024-01-05
# When the content was published (public-facing)
publishedAt: 2024-01-15
# Last content modification (triggers "Updated" badge)
updatedAt: 2024-01-22
# Date displayed to readers (may differ from publishedAt for editorial reasons)
date: 2024-01-15
# Scheduled publication (for CMS workflows)
scheduledFor: 2024-02-01T09:00:00Z
# Content expiration (for time-sensitive content)
expiresAt: 2024-12-31
---Date Handling Across Frameworks
Gatsby (GraphQL date formatting):
graphql example
query {
mdx(frontmatter: { slug: { eq: "my-post" } }) {
frontmatter {
date(formatString: "MMMM DD, YYYY")
updatedAt(fromNow: true) # "3 days ago"
}
}
}Next.js (manual formatting):
jsx example
import { format, formatDistance } from 'date-fns';
function PostHeader({ frontmatter }) {
return (
<header>
<time dateTime={frontmatter.date}>
{format(new Date(frontmatter.date), 'MMMM d, yyyy')}
</time>
{frontmatter.updatedAt && (
<span className="updated">
Updated {formatDistance(new Date(frontmatter.updatedAt), new Date(), { addSuffix: true })}
</span>
)}
</header>
);
}Categories and Tags
Categories and tags are your content taxonomy — the system that helps readers find related content and helps you keep things organized.
yaml example
---
# Single primary category (hierarchical)
category: "React"
# Subcategory for deeper classification
subcategory: "Hooks"
# Tags (flat, non-hierarchical, multiple allowed)
tags:
- react
- hooks
- state-management
- performance
# Series/collection grouping
series:
name: "React Fundamentals"
order: 3
total: 8
# Related content (manual curation)
relatedPosts:
- "intro-to-react-hooks"
- "useeffect-deep-dive"
- "custom-hooks-patterns"
---Building a Tag Index
Example
// lib/tags.ts
import { allPosts } from 'contentlayer/generated';
export function getTagCounts(): Record<string, number> {
const tagCounts: Record<string, number> = {};
allPosts.forEach(post => {
post.tags?.forEach(tag => {
tagCounts[tag] = (tagCounts[tag] || 0) + 1;
});
});
return tagCounts;
}
export function getPostsByTag(tag: string) {
return allPosts.filter(post =>
post.tags?.includes(tag) && !post.draft
);
}
Custom Metadata Fields
Beyond the standard stuff, you can add whatever metadata your content system needs.
yaml example
---
# Content characteristics
difficulty: "intermediate"
readingTime: 8
wordCount: 2400
prerequisites:
- "basic-javascript"
- "intro-to-react"
# Visual presentation
heroImage: "/images/posts/generics-hero.png"
heroImageAlt: "TypeScript generics diagram showing type flow"
theme: "dark"
accentColor: "#3178c6"
# Interactive features
hasCodePlayground: true
hasQuiz: true
interactiveExamples: 3
# Content versioning
contentVersion: "2.1"
targetFrameworkVersion: "React 18+"
lastReviewedAt: 2024-01-20
reviewedBy: "tech-lead"
# Analytics and tracking
contentGroup: "tutorials"
experimentId: "new-tutorial-format-2024"
---Metadata Schemas
A formal schema keeps things consistent across all your content and catches errors at build time.
Example
// schemas/content.ts
import { z } from 'zod';
// Reusable sub-schemas
const authorSchema = z.object({
name: z.string(),
email: z.string().email().optional(),
avatar: z.string().optional(),
twitter: z.string().optional(),
github: z.string().optional(),
});
const seriesSchema = z.object({
name: z.string(),
order: z.number().positive(),
total: z.number().positive().optional(),
});
// Main document schema
export const documentSchema = z.object({
title: z.string().min(5).max(100),
description: z.string().max(200),
author: z.union([z.string(), authorSchema]),
// Dates
date: z.coerce.date(),
updatedAt: z.coerce.date().optional(),
publishedAt: z.coerce.date().optional(),
// Taxonomy
category: z.enum([
"Tutorial", "Guide", "Reference",
"Blog", "Case Study", "News"
]),
tags: z.array(z.string()).min(1).max(8),
series: seriesSchema.optional(),
// Content meta
difficulty: z.enum(["beginner", "intermediate", "advanced"]).default("beginner"),
draft: z.boolean().default(false),
featured: z.boolean().default(false),
// Custom fields
heroImage: z.string().optional(),
readingTime: z.number().optional(),
prerequisites: z.array(z.string()).default([]),
});
Using Metadata in Templates
Metadata drives your templates. One layout component adapts to whatever the frontmatter says:
Example
// components/DocumentLayout.jsx
export default function DocumentLayout({ frontmatter, children }) {
return (
<article className={`post post--${frontmatter.difficulty}`}>
{/* Hero section driven by metadata */}
{frontmatter.heroImage && (
<div className="post-hero">
<img src={frontmatter.heroImage} alt={frontmatter.title} />
</div>
)}
{/* Header with metadata */}
<header className="post-header">
<div className="post-meta">
<span className="category">{frontmatter.category}</span>
<span className="difficulty">{frontmatter.difficulty}</span>
{frontmatter.readingTime && (
<span className="reading-time">{frontmatter.readingTime} min read</span>
)}
</div>
<h1>{frontmatter.title}</h1>
<p className="description">{frontmatter.description}</p>
</header>
{/* Prerequisites block */}
{frontmatter.prerequisites?.length > 0 && (
<aside className="prerequisites">
<h3>Prerequisites</h3>
<ul>
{frontmatter.prerequisites.map(prereq => (
<li key={prereq}>{prereq}</li>
))}
</ul>
</aside>
)}
{/* Series navigation */}
{frontmatter.series && (
<nav className="series-nav">
Part {frontmatter.series.order} of {frontmatter.series.total} in
<strong> {frontmatter.series.name}</strong>
</nav>
)}
{/* Main content */}
<div className="post-content">
{children}
</div>
{/* Tags footer */}
<footer className="post-footer">
<div className="tags">
{frontmatter.tags.map(tag => (
<a key={tag} href={`/tags/${tag}`} className="tag">
#{tag}
</a>
))}
</div>
</footer>
</article>
);
}
Best Practices
- Define your schema first — Before writing content, decide what fields exist, which are required, and what values are valid.
- Stick with ISO dates —
YYYY-MM-DDor full datetime. No ambiguity, no timezone confusion.
- Keep author data DRY — Store detailed author info in a separate data file. Reference by ID in frontmatter instead of copy-pasting bios into every post.
- Control your tags — Without a controlled vocabulary, you'll end up with "react", "React", and "ReactJS" as three separate tags. Pick one and enforce it.
- Compute what you can —
readingTimeandwordCountcan be generated at build time. Don't make authors maintain these by hand.
- Version your schema — As your content system grows, track schema changes and migrate existing content when you add or rename fields.
- Write a field reference — Keep a doc showing all available fields, expected formats, and examples. Your content authors will thank you.
Exam Focus
Revise definitions, diagrams, examples, and short-answer points for Document Metadata 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, frontmatter, metadata, document metadata in mdx
Related MDX Tutorial Topics
Continue learning this concept
FrontmatterFrontmatter BasicsWhat frontmatter is, how MDX uses it, YAML syntax you need to know, and how to get at that data in your components.FrontmatterPage Configuration via FrontmatterHow to control layout, sidebar, navigation, table of contents, draft mode, and feature flags — all from your MDX frontmatter.FrontmatterSEO Fields in FrontmatterHow to set up frontmatter fields that control how your MDX pages look in Google, Twitter, Facebook, and rich snippets.AdvancedInteractive 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.