SEO Optimization for MDX Content

How to make your MDX docs show up in search results — keywords, meta tags, headings, internal links, and technical SEO that actually works.

You wrote great docs. Now people need to actually find them. MDX renders to HTML, which search engines already understand — but there's a lot you can do to push your content higher in rankings.

Why SEO Matters for Documentation

Your docs are competing with every other result on page one. If Google can't index and rank your pages properly, developers searching for answers will never land on your site. Better SEO = more readers, more contributors, more adoption.

Keyword Placement Strategy

Put your keywords where search engines look first:

Primary Keyword Locations

mdx example

# Installing MDX with Next.js              {/* ← H1 contains primary keyword */}

Learn how to **install MDX** in your        {/* ← First paragraph, bolded */}
Next.js application with full configuration
options and plugin support.

## Prerequisites for MDX Installation       {/* ← H2 with keyword variation */}

## Step-by-Step MDX Setup                   {/* ← Another H2 with variation */}

Keyword Density Guidelines

Title/H1: Include primary keyword naturally
First 100 words: Mention the primary keyword once
Headings: Use keyword variations in 30–50% of H2s
Body text: 1–2% keyword density (don't stuff)
Image alt text: Include keywords where natural
URL/slug: Include primary keyword

Heading Structure for SEO

Search engines read your headings to figure out what your page is about and how it's organized:

mdx example

{/* ✅ SEO-optimized heading structure */}
# How to Use MDX Components in React        {/* Clear, keyword-rich H1 */}

## What Are MDX Components?                  {/* Targets featured snippet */}

## Creating Your First MDX Component         {/* Action-oriented, specific */}

### Props and Configuration                  {/* Logical sub-topic */}

### Styling MDX Components                   {/* Related sub-topic */}

## Advanced MDX Component Patterns           {/* Signals depth of content */}

## Troubleshooting Common Issues             {/* Captures error-related searches */}

{/* ❌ Poor heading structure for SEO */}
# Components
## About
## Usage
## More Info

Heading Best Practices for SEO

Practice	Example
Include target keyword	"Configuring MDX Plugins" not "Configuration"
Use question format	"How Do MDX Plugins Work?" (targets voice search)
Be specific	"MDX Remark Plugin Setup" not "Setup"
Match search intent	"Fix MDX Build Errors" (matches what users search)
Keep under 60 chars	Displays fully in search results

Meta Tags and Frontmatter

Your frontmatter controls what shows up in search results and social shares:

Example

--- title: "MDX Plugin Development Guide | MDX Tutorial" description: "Learn to build custom remark and rehype plugins for MDX. Covers AST manipulation, plugin architecture, and testing strategies." keywords: ["mdx plugins", "remark plugin", "rehype plugin", "mdx customization"] canonical: "https://mdx-tutorial.dev/guides/plugin-development" openGraph: title: "MDX Plugin Development Guide" description: "Build custom MDX plugins from scratch" image: "/og/plugin-development.png" type: "article" twitter: card: "summary_large_image" title: "MDX Plugin Development Guide" image: "/twitter/plugin-development.png" ---

Meta Tag Optimization Rules

Title: 50–60 characters, keyword at the beginning
Description: 150–160 characters, include a call to action
Canonical URL: Prevent duplicate content issues
Open Graph: Control social sharing appearance
Keywords: Include 3–5 relevant terms

Internal Linking Strategy

Internal links spread page authority around your site and help crawlers find your content:

Example

## Setting Up MDX Before configuring plugins, make sure you've completed the [MDX installation guide](/getting-started/installation). For framework-specific setup, see our [Next.js integration tutorial](/frameworks/nextjs). {/* Use descriptive anchor text */} ✅ Learn more in our [MDX component styling guide](/guides/styling) ❌ For more info, [click here](/guides/styling) {/* Link to related content naturally */} MDX supports [custom components](/components/overview) that you can import into any document. These work alongside the built-in [Markdown syntax](/basics/markdown-syntax) you already know.

Internal Linking Rules

3–5 internal links per page minimum
Descriptive anchor text — tells users and search engines what's at the destination
Link to deep pages — not just the homepage
Contextual relevance — link where it makes sense in the content flow
Update old content — add links to new pages from existing content

URL Structure

Clean URLs help both search engines and humans:

Example

✅ Good URL structure: /docs/getting-started/installation /docs/guides/custom-components /docs/api/compiler-options /docs/troubleshooting/build-errors ❌ Poor URL structure: /docs/page1 /docs/gs-inst /docs/2024/01/15/post-about-things /docs/category/subcategory/subsubcategory/deep/page

URL Guidelines

Use kebab-case: /custom-components not /customComponents
Keep URLs short: 3–5 words after domain
Include target keyword in the slug
Avoid date-based URLs for evergreen content
Limit nesting depth to 3 levels maximum
Use trailing slashes consistently (pick one approach)

Image Alt Text

Every image needs descriptive alt text. No exceptions:

Example

{/* ✅ Descriptive, includes context */} ![MDX compilation pipeline showing source file transforming through remark and rehype plugins to final HTML output](/images/mdx-pipeline.png) {/* ✅ Using JSX for more control */} <Image src="/images/mdx-editor-screenshot.png" alt="VS Code editor with MDX syntax highlighting showing a component import and JSX usage within markdown content" width={800} height={450} loading="lazy" /> {/* ❌ Missing or unhelpful alt text */} ![image](/images/screenshot.png) ![](/images/diagram.png)

Schema Markup

Structured data helps search engines show rich results (those fancy snippets with ratings, dates, etc.):

jsx title="components/ArticleSchema.jsx" example

export function ArticleSchema({ title, description, date, author }) {
  const schema = {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    "headline": title,
    "description": description,
    "datePublished": date,
    "author": {
      "@type": "Person",
      "name": author
    },
    "publisher": {
      "@type": "Organization",
      "name": "MDX Tutorial"
    }
  };

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
    />
  );
}

mdx title="docs/guides/components.mdx" example

import { ArticleSchema } from '../components/ArticleSchema';

<ArticleSchema
  title="MDX Components Guide"
  description="Learn to create and use custom components in MDX"
  date="2024-01-15"
  author="MDX Tutorial Team"
/>

# MDX Components Guide
...

Sitemap Generation

Make sure search engines can find all your pages:

Example

import { globby } from 'globby'; import { writeFileSync } from 'fs'; async function generateSitemap() { const pages = await globby(['docs/**/*.mdx']); const baseUrl = 'https://mdx-tutorial.dev'; const sitemap = `<?xml version="1.0" encoding="UTF-8"?> <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> ${pages.map(page => { const path = page .replace('docs/', '/') .replace('.mdx', ''); return ` <url> <loc>${baseUrl}${path}</loc> <lastmod>${new Date().toISOString().split('T')[0]}</lastmod> <changefreq>weekly</changefreq> <priority>${path === '/index' ? '1.0' : '0.8'}</priority> </url>`; }).join('')} </urlset>`; writeFileSync('public/sitemap.xml', sitemap); } generateSitemap();

Page Speed Optimization

Google cares about speed. Slow pages rank lower. Here's what to do in your MDX:

MDX-Specific Performance Tips

Example

{/* Lazy-load images below the fold */} <Image src="/diagram.png" alt="..." loading="lazy" /> {/* Use dynamic imports for heavy components */} import dynamic from 'next/dynamic'; const HeavyChart = dynamic(() => import('../components/Chart'), { loading: () => <p>Loading chart...</p>, ssr: false }); {/* Minimize client-side JavaScript */} {/* Prefer static content over interactive when possible */}

Performance Checklist

[ ] Images optimized and properly sized
[ ] Lazy loading for below-fold content
[ ] Minimal JavaScript bundle
[ ] Static generation where possible (SSG over SSR)
[ ] CDN for assets
[ ] Compressed responses (gzip/brotli)
[ ] Minimal third-party scripts

Content Freshness

Search engines reward pages that get updated. Stale content drops in rankings over time.

Review quarterly — Update statistics, links, and examples
Add "last updated" dates — Show search engines content is maintained
Expand existing content — Add sections rather than creating thin new pages
Fix broken links — Regularly audit and repair link rot
Update code examples — Keep dependencies current

mdx example

---
title: "MDX Configuration Guide"
date: "2024-01-15"
lastUpdated: "2024-03-20"      {/* ← Track when content was refreshed */}
---

Summary

SEO for MDX boils down to this: help search engines understand your content, and make it fast to load. Clear structure, strategic keywords, good performance, regular updates. But honestly, the single best thing you can do for SEO is write content that genuinely helps people. Everything else is just optimization on top of that.

You wrote great docs. Now people need to actually find them. MDX renders to HTML, which search engines already understand — but there's a lot you can do to push your content higher in rankings.

Why SEO Matters for Documentation

Keyword Placement Strategy

Put your keywords where search engines look first:

Primary Keyword Locations

mdx example

# Installing MDX with Next.js              {/* ← H1 contains primary keyword */}

Learn how to **install MDX** in your        {/* ← First paragraph, bolded */}
Next.js application with full configuration
options and plugin support.

## Prerequisites for MDX Installation       {/* ← H2 with keyword variation */}

## Step-by-Step MDX Setup                   {/* ← Another H2 with variation */}

Keyword Density Guidelines

Title/H1: Include primary keyword naturally
First 100 words: Mention the primary keyword once
Headings: Use keyword variations in 30–50% of H2s
Body text: 1–2% keyword density (don't stuff)
Image alt text: Include keywords where natural
URL/slug: Include primary keyword

Heading Structure for SEO

Search engines read your headings to figure out what your page is about and how it's organized:

mdx example

{/* ✅ SEO-optimized heading structure */}
# How to Use MDX Components in React        {/* Clear, keyword-rich H1 */}

## What Are MDX Components?                  {/* Targets featured snippet */}

## Creating Your First MDX Component         {/* Action-oriented, specific */}

### Props and Configuration                  {/* Logical sub-topic */}

### Styling MDX Components                   {/* Related sub-topic */}

## Advanced MDX Component Patterns           {/* Signals depth of content */}

## Troubleshooting Common Issues             {/* Captures error-related searches */}

{/* ❌ Poor heading structure for SEO */}
# Components
## About
## Usage
## More Info

Heading Best Practices for SEO

Practice	Example
Include target keyword	"Configuring MDX Plugins" not "Configuration"
Use question format	"How Do MDX Plugins Work?" (targets voice search)
Be specific	"MDX Remark Plugin Setup" not "Setup"
Match search intent	"Fix MDX Build Errors" (matches what users search)
Keep under 60 chars	Displays fully in search results

Meta Tags and Frontmatter

Your frontmatter controls what shows up in search results and social shares:

Example

Meta Tag Optimization Rules

Title: 50–60 characters, keyword at the beginning
Description: 150–160 characters, include a call to action
Canonical URL: Prevent duplicate content issues
Open Graph: Control social sharing appearance
Keywords: Include 3–5 relevant terms

Internal Linking Strategy

Internal links spread page authority around your site and help crawlers find your content:

Example

Internal Linking Rules

3–5 internal links per page minimum
Descriptive anchor text — tells users and search engines what's at the destination
Link to deep pages — not just the homepage
Contextual relevance — link where it makes sense in the content flow
Update old content — add links to new pages from existing content

URL Structure

Clean URLs help both search engines and humans:

Example

URL Guidelines

Use kebab-case: /custom-components not /customComponents
Keep URLs short: 3–5 words after domain
Include target keyword in the slug
Avoid date-based URLs for evergreen content
Limit nesting depth to 3 levels maximum
Use trailing slashes consistently (pick one approach)

Image Alt Text

Every image needs descriptive alt text. No exceptions:

Example

Schema Markup

Structured data helps search engines show rich results (those fancy snippets with ratings, dates, etc.):

jsx title="components/ArticleSchema.jsx" example

export function ArticleSchema({ title, description, date, author }) {
  const schema = {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    "headline": title,
    "description": description,
    "datePublished": date,
    "author": {
      "@type": "Person",
      "name": author
    },
    "publisher": {
      "@type": "Organization",
      "name": "MDX Tutorial"
    }
  };

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
    />
  );
}

mdx title="docs/guides/components.mdx" example

import { ArticleSchema } from '../components/ArticleSchema';

<ArticleSchema
  title="MDX Components Guide"
  description="Learn to create and use custom components in MDX"
  date="2024-01-15"
  author="MDX Tutorial Team"
/>

# MDX Components Guide
...

Sitemap Generation

Make sure search engines can find all your pages:

Example

Page Speed Optimization

Google cares about speed. Slow pages rank lower. Here's what to do in your MDX:

MDX-Specific Performance Tips

Example

Performance Checklist

[ ] Images optimized and properly sized
[ ] Lazy loading for below-fold content
[ ] Minimal JavaScript bundle
[ ] Static generation where possible (SSG over SSR)
[ ] CDN for assets
[ ] Compressed responses (gzip/brotli)
[ ] Minimal third-party scripts

Content Freshness

Search engines reward pages that get updated. Stale content drops in rankings over time.

Review quarterly — Update statistics, links, and examples
Add "last updated" dates — Show search engines content is maintained
Expand existing content — Add sections rather than creating thin new pages
Fix broken links — Regularly audit and repair link rot
Update code examples — Keep dependencies current

mdx example

---
title: "MDX Configuration Guide"
date: "2024-01-15"
lastUpdated: "2024-03-20"      {/* ← Track when content was refreshed */}
---

Why SEO Matters for Documentation

Keyword Placement Strategy

Primary Keyword Locations

Keyword Density Guidelines

Heading Structure for SEO

Heading Best Practices for SEO

Meta Tags and Frontmatter

Meta Tag Optimization Rules

Internal Linking Strategy

Internal Linking Rules

URL Structure

URL Guidelines

Image Alt Text

Schema Markup

Sitemap Generation

Page Speed Optimization

MDX-Specific Performance Tips

Performance Checklist

Content Freshness

Summary

Continue learning this concept

Why SEO Matters for Documentation

Keyword Placement Strategy

Primary Keyword Locations

Keyword Density Guidelines

Heading Structure for SEO

Heading Best Practices for SEO

Meta Tags and Frontmatter

Meta Tag Optimization Rules

Internal Linking Strategy

Internal Linking Rules

URL Structure

URL Guidelines

Image Alt Text

Schema Markup

Sitemap Generation

Page Speed Optimization

MDX-Specific Performance Tips

Performance Checklist

Content Freshness

Summary

Continue learning this concept