SEO Fields in Frontmatter

How to set up frontmatter fields that control how your MDX pages look in Google, Twitter, Facebook, and rich snippets.

Why SEO Metadata Matters

SEO metadata controls how your content shows up in Google results, social feeds, and link previews. Skip it, and your framework picks boring defaults. Set it properly, and you decide exactly what people see before they click.

You're writing for three audiences here: search engines (Google, Bing), social platforms (Facebook, Twitter, LinkedIn), and structured data consumers (rich snippets, knowledge panels, AI assistants).

Complete SEO Frontmatter Example

yaml example

Title Tag Optimization

The title tag is the biggest single lever you have for on-page SEO. It shows in browser tabs, search result headlines, and social shares.

You can (and should) have a different SEO title from your content heading:

yaml example

---
# Content title (used in the page heading)
title: "Understanding React Server Components"

# SEO title (used in <title> tag - can differ from content title)
seo:
  title: "React Server Components Explained | Complete Guide 2024"
---

Title Tag Best Practices

Length: 50-60 characters max. Google truncates anything longer.
Keywords: Put your primary keyword near the front.
Branding: Append your site name with a separator: "Topic | Site Name"
Uniqueness: Every page needs its own title. No duplicates.
Clarity: Make it descriptive and clickable — this is your search result headline.

Framework Implementation

Next.js:

Example

// app/blog/[slug]/page.tsx import { Metadata } from 'next'; export async function generateMetadata({ params }): Promise<Metadata> { const post = await getPost(params.slug); const fm = post.frontmatter; return { title: fm.seo?.title || `${fm.title} | MySite`, description: fm.seo?.description || fm.description, }; }

Docusaurus:

yaml example

---
title: React Server Components
# Docusaurus uses title for both heading and <title> tag
# Override with a plugin for custom SEO titles
---

Meta Description

The meta description shows below your title in search results. It's not a ranking factor directly, but it massively affects whether people click.

yaml example

---
description: "Learn how React Server Components work, when to use them, and how they differ from Client Components. Includes migration guide and performance benchmarks."

# Separate SEO description if you want a shorter, more keyword-rich version
seo:
  description: "React Server Components guide: how they work, performance benefits, migration steps & real-world examples. Updated for Next.js 14."
---

Meta Description Guidelines

Length: 150-160 characters. Google cuts off around 155.
Content: Summarize what the reader gets from this page.
Keywords: Include target keywords naturally (Google bolds them in results).
Call to action: Use action words — "Learn", "Discover", "Master".
Uniqueness: Never copy-paste descriptions across pages.
No quotes: Avoid double quotes — Google may truncate at them.

Open Graph (og:) Fields

Open Graph controls how your content looks when shared on Facebook, LinkedIn, Discord, Slack, and anything else that supports the protocol.

Example

--- openGraph: # Required fields title: "React Server Components: A Deep Dive" description: "Understand how RSC works under the hood with diagrams and code examples." image: "/images/og/rsc-deep-dive.png" # Recommended fields type: "article" # article, website, profile, book url: "https://mysite.com/blog/rsc-deep-dive" locale: "en_US" siteName: "MyDevBlog" # Image specifications imageWidth: 1200 # Recommended: 1200px imageHeight: 630 # Recommended: 630px (1.91:1 ratio) imageAlt: "Diagram showing React Server Components architecture" imageType: "image/png" # Article-specific article: publishedTime: "2024-01-15T10:00:00Z" modifiedTime: "2024-01-20T14:30:00Z" author: "https://mysite.com/authors/jane" section: "Technology" tags: ["React", "Server Components", "Next.js"] ---

Rendering Open Graph Tags

Example

// components/SEOHead.jsx export function SEOHead({ frontmatter }) { const og = frontmatter.openGraph || {}; const baseUrl = "https://mysite.com"; return ( <head> <meta property="og:title" content={og.title || frontmatter.title} /> <meta property="og:description" content={og.description || frontmatter.description} /> <meta property="og:type" content={og.type || "article"} /> <meta property="og:url" content={`${baseUrl}${frontmatter.slug}`} /> {og.image && ( <> <meta property="og:image" content={`${baseUrl}${og.image}`} /> <meta property="og:image:width" content={og.imageWidth || "1200"} /> <meta property="og:image:height" content={og.imageHeight || "630"} /> <meta property="og:image:alt" content={og.imageAlt || frontmatter.title} /> </> )} <meta property="og:locale" content={og.locale || "en_US"} /> <meta property="og:site_name" content={og.siteName || "MySite"} /> </head> ); }

Twitter Card Fields

Twitter (X) has its own meta tags for link previews. If you don't set them, it falls back to Open Graph — but you get better results with dedicated Twitter tags.

yaml example

---
twitter:
  # Card type: summary, summary_large_image, app, player
  card: "summary_large_image"
  
  # Override title/description for Twitter specifically
  title: "React Server Components Deep Dive 🚀"
  description: "How RSC works under the hood — with diagrams!"
  
  # Twitter-specific image (can differ from OG image)
  # Aspect ratio: 2:1 for summary_large_image, 1:1 for summary
  image: "/images/twitter/rsc-card.png"
  imageAlt: "React Server Components architecture diagram"
  
  # Attribution
  site: "@mydevblog"      # Site's Twitter handle
  creator: "@janedev"     # Author's Twitter handle
---

Card Type Comparison

Card Type	Image Size	Use Case
`summary`	144×144 (min)	Short posts, quick links
`summary_large_image`	1200×600	Blog posts, tutorials, articles
`app`	App icon	App download promotions
`player`	Video frame	Video/audio content

Canonical URL

The canonical URL tells search engines "this is the official version of this page." It prevents duplicate content issues when the same content lives at multiple URLs.

yaml example

---
seo:
  # Absolute canonical URL
  canonical: "https://mysite.com/blog/react-server-components"
  
  # Use cases:
  # - Content syndicated across multiple sites
  # - Pages accessible via multiple URLs
  # - Paginated content pointing to page 1
  # - HTTP/HTTPS or www/non-www duplicates
---

Implementation

Example

// Rendering canonical link function CanonicalTag({ frontmatter, currentUrl }) { const canonical = frontmatter.seo?.canonical || currentUrl; return <link rel="canonical" href={canonical} />; }

Robots Directives

Control how search engines crawl and index individual pages:

yaml example

---
seo:
  # Standard directives
  robots: "index, follow"        # Default: allow indexing and link following
  
  # Common configurations:
  # robots: "noindex, follow"    # Don't index but follow links (draft pages)
  # robots: "index, nofollow"    # Index but don't follow outbound links
  # robots: "noindex, nofollow"  # Completely hide from search (private pages)
  # robots: "noarchive"          # Don't show cached version
  # robots: "nosnippet"          # Don't show description snippet
  # robots: "max-snippet:160"    # Limit snippet length
  
  # Google-specific
  googlebot: "max-image-preview:large, max-video-preview:-1"
---

Conditional Robots Based on Draft Status

Example

function RobotsTag({ frontmatter }) { // Automatically noindex draft content const robots = frontmatter.draft ? "noindex, nofollow" : (frontmatter.seo?.robots || "index, follow"); return <meta name="robots" content={robots} />; }

Structured Data / JSON-LD

Structured data helps Google show rich results — recipe cards, FAQ dropdowns, how-to steps, article info panels. You define the data in frontmatter, then render it as JSON-LD.

yaml example

---
structuredData:
  type: "TechArticle"
  headline: "Complete Guide to CSS Grid Layout"
  description: "Master CSS Grid with practical examples and responsive patterns."
  datePublished: "2024-01-15"
  dateModified: "2024-01-20"
  author:
    name: "Jane Developer"
    url: "https://mysite.com/authors/jane"
  publisher:
    name: "DevBlog"
    logo: "https://mysite.com/logo.png"
  image: "https://mysite.com/images/css-grid-hero.png"
  wordCount: 3500
  proficiencyLevel: "Beginner"
  mainEntityOfPage: "https://mysite.com/guides/css-grid"

# For FAQ pages
faq:
  - question: "What is CSS Grid?"
    answer: "CSS Grid is a two-dimensional layout system for the web."
  - question: "Is CSS Grid supported in all browsers?"
    answer: "CSS Grid has over 96% browser support as of 2024."
---

Rendering JSON-LD from Frontmatter

Example

Keyword Optimization in Frontmatter

Google doesn't use the keywords meta tag for ranking anymore. But tracking keywords in your frontmatter is still useful for content audits, internal search, and keeping your writing focused.

yaml example

---
seo:
  # Primary target keyword
  primaryKeyword: "CSS Grid layout"
  
  # Secondary keywords for semantic coverage
  secondaryKeywords:
    - "CSS Grid tutorial"
    - "responsive grid"
    - "grid-template-columns"
    - "CSS layout system"
  
  # Search intent alignment
  searchIntent: "informational"  # informational, navigational, transactional, commercial
  
  # Internal keyword tracking (not rendered)
  keywordDifficulty: 45
  searchVolume: 12000
  targetPosition: 3
---

Building a Content Audit Tool

Example

// scripts/audit-seo.ts import { allPosts } from 'contentlayer/generated'; function auditSEO() { const issues: string[] = []; allPosts.forEach(post => { const { title, description, seo } = post; // Title length check const seoTitle = seo?.title || title; if (seoTitle.length > 60) { issues.push(`${post.slug}: Title too long (${seoTitle.length} chars)`); } // Description check const desc = seo?.description || description; if (!desc) { issues.push(`${post.slug}: Missing meta description`); } else if (desc.length > 160) { issues.push(`${post.slug}: Description too long (${desc.length} chars)`); } // Image check if (!post.openGraph?.image) { issues.push(`${post.slug}: Missing OG image`); } // Canonical check if (!seo?.canonical) { issues.push(`${post.slug}: No canonical URL defined`); } }); return issues; }

Complete SEO Component

Here's a full component that takes your frontmatter and spits out all the meta tags you need:

Example

// components/SEO.jsx export function SEO({ frontmatter, url }) { const seo = frontmatter.seo || {}; const og = frontmatter.openGraph || {}; const tw = frontmatter.twitter || {}; const baseUrl = "https://mysite.com"; const title = seo.title || frontmatter.title; const description = seo.description || frontmatter.description; const image = og.image ? `${baseUrl}${og.image}` : null; const canonical = seo.canonical || `${baseUrl}${url}`; return ( <> {/* Primary Meta */} <title>{title}</title> <meta name="description" content={description} /> <link rel="canonical" href={canonical} /> <meta name="robots" content={frontmatter.draft ? "noindex" : (seo.robots || "index, follow")} /> {/* Open Graph */} <meta property="og:title" content={og.title || title} /> <meta property="og:description" content={og.description || description} /> <meta property="og:type" content={og.type || "article"} /> <meta property="og:url" content={canonical} /> {image && <meta property="og:image" content={image} />} {/* Twitter */} <meta name="twitter:card" content={tw.card || "summary_large_image"} /> <meta name="twitter:title" content={tw.title || title} /> <meta name="twitter:description" content={tw.description || description} /> {tw.image && <meta name="twitter:image" content={`${baseUrl}${tw.image}`} />} {tw.creator && <meta name="twitter:creator" content={tw.creator} />} </> ); }

Best Practices

Write explicit SEO titles and descriptions — Don't rely on auto-generated fallbacks. Craft each one by hand.

Create platform-specific images — OG images (1200×630) and Twitter images (1200×600) have different dimensions. Design separate assets when you can.

Automate canonical URLs — Generate them from file paths so you don't mess them up manually. Allow frontmatter overrides for syndicated content.

Auto-noindex drafts — Build logic that blocks draft content from indexing regardless of what someone sets manually.

Validate with testing tools — Use Facebook Sharing Debugger, Twitter Card Validator, and Google's Rich Results Test to check your work.

Add structured data for rich snippets — JSON-LD for articles, FAQs, and how-tos can get you those fancy search result cards.

Audit regularly — Run automated checks for missing descriptions, oversized titles, broken images, and missing structured data.

Why SEO Metadata Matters

Complete SEO Frontmatter Example

yaml example

Title Tag Optimization

The title tag is the biggest single lever you have for on-page SEO. It shows in browser tabs, search result headlines, and social shares.

You can (and should) have a different SEO title from your content heading:

yaml example

---
# Content title (used in the page heading)
title: "Understanding React Server Components"

# SEO title (used in <title> tag - can differ from content title)
seo:
  title: "React Server Components Explained | Complete Guide 2024"
---

Title Tag Best Practices

Length: 50-60 characters max. Google truncates anything longer.
Keywords: Put your primary keyword near the front.
Branding: Append your site name with a separator: "Topic | Site Name"
Uniqueness: Every page needs its own title. No duplicates.
Clarity: Make it descriptive and clickable — this is your search result headline.

Framework Implementation

Next.js:

Example

Docusaurus:

yaml example

---
title: React Server Components
# Docusaurus uses title for both heading and <title> tag
# Override with a plugin for custom SEO titles
---

Meta Description

The meta description shows below your title in search results. It's not a ranking factor directly, but it massively affects whether people click.

yaml example

---
description: "Learn how React Server Components work, when to use them, and how they differ from Client Components. Includes migration guide and performance benchmarks."

# Separate SEO description if you want a shorter, more keyword-rich version
seo:
  description: "React Server Components guide: how they work, performance benefits, migration steps & real-world examples. Updated for Next.js 14."
---

Meta Description Guidelines

Length: 150-160 characters. Google cuts off around 155.
Content: Summarize what the reader gets from this page.
Keywords: Include target keywords naturally (Google bolds them in results).
Call to action: Use action words — "Learn", "Discover", "Master".
Uniqueness: Never copy-paste descriptions across pages.
No quotes: Avoid double quotes — Google may truncate at them.

Open Graph (og:) Fields

Open Graph controls how your content looks when shared on Facebook, LinkedIn, Discord, Slack, and anything else that supports the protocol.

Example

Rendering Open Graph Tags

Example

Twitter Card Fields

Twitter (X) has its own meta tags for link previews. If you don't set them, it falls back to Open Graph — but you get better results with dedicated Twitter tags.

yaml example

---
twitter:
  # Card type: summary, summary_large_image, app, player
  card: "summary_large_image"
  
  # Override title/description for Twitter specifically
  title: "React Server Components Deep Dive 🚀"
  description: "How RSC works under the hood — with diagrams!"
  
  # Twitter-specific image (can differ from OG image)
  # Aspect ratio: 2:1 for summary_large_image, 1:1 for summary
  image: "/images/twitter/rsc-card.png"
  imageAlt: "React Server Components architecture diagram"
  
  # Attribution
  site: "@mydevblog"      # Site's Twitter handle
  creator: "@janedev"     # Author's Twitter handle
---

Card Type Comparison

Card Type	Image Size	Use Case
`summary`	144×144 (min)	Short posts, quick links
`summary_large_image`	1200×600	Blog posts, tutorials, articles
`app`	App icon	App download promotions
`player`	Video frame	Video/audio content

Canonical URL

The canonical URL tells search engines "this is the official version of this page." It prevents duplicate content issues when the same content lives at multiple URLs.

yaml example

---
seo:
  # Absolute canonical URL
  canonical: "https://mysite.com/blog/react-server-components"
  
  # Use cases:
  # - Content syndicated across multiple sites
  # - Pages accessible via multiple URLs
  # - Paginated content pointing to page 1
  # - HTTP/HTTPS or www/non-www duplicates
---

Implementation

Example

// Rendering canonical link function CanonicalTag({ frontmatter, currentUrl }) { const canonical = frontmatter.seo?.canonical || currentUrl; return <link rel="canonical" href={canonical} />; }

Robots Directives

Control how search engines crawl and index individual pages:

yaml example

---
seo:
  # Standard directives
  robots: "index, follow"        # Default: allow indexing and link following
  
  # Common configurations:
  # robots: "noindex, follow"    # Don't index but follow links (draft pages)
  # robots: "index, nofollow"    # Index but don't follow outbound links
  # robots: "noindex, nofollow"  # Completely hide from search (private pages)
  # robots: "noarchive"          # Don't show cached version
  # robots: "nosnippet"          # Don't show description snippet
  # robots: "max-snippet:160"    # Limit snippet length
  
  # Google-specific
  googlebot: "max-image-preview:large, max-video-preview:-1"
---

Conditional Robots Based on Draft Status

Example

Structured Data / JSON-LD

Structured data helps Google show rich results — recipe cards, FAQ dropdowns, how-to steps, article info panels. You define the data in frontmatter, then render it as JSON-LD.

yaml example

---
structuredData:
  type: "TechArticle"
  headline: "Complete Guide to CSS Grid Layout"
  description: "Master CSS Grid with practical examples and responsive patterns."
  datePublished: "2024-01-15"
  dateModified: "2024-01-20"
  author:
    name: "Jane Developer"
    url: "https://mysite.com/authors/jane"
  publisher:
    name: "DevBlog"
    logo: "https://mysite.com/logo.png"
  image: "https://mysite.com/images/css-grid-hero.png"
  wordCount: 3500
  proficiencyLevel: "Beginner"
  mainEntityOfPage: "https://mysite.com/guides/css-grid"

# For FAQ pages
faq:
  - question: "What is CSS Grid?"
    answer: "CSS Grid is a two-dimensional layout system for the web."
  - question: "Is CSS Grid supported in all browsers?"
    answer: "CSS Grid has over 96% browser support as of 2024."
---

Rendering JSON-LD from Frontmatter

Example

Keyword Optimization in Frontmatter

Google doesn't use the keywords meta tag for ranking anymore. But tracking keywords in your frontmatter is still useful for content audits, internal search, and keeping your writing focused.

yaml example

---
seo:
  # Primary target keyword
  primaryKeyword: "CSS Grid layout"
  
  # Secondary keywords for semantic coverage
  secondaryKeywords:
    - "CSS Grid tutorial"
    - "responsive grid"
    - "grid-template-columns"
    - "CSS layout system"
  
  # Search intent alignment
  searchIntent: "informational"  # informational, navigational, transactional, commercial
  
  # Internal keyword tracking (not rendered)
  keywordDifficulty: 45
  searchVolume: 12000
  targetPosition: 3
---

Building a Content Audit Tool

Example

Complete SEO Component

Here's a full component that takes your frontmatter and spits out all the meta tags you need:

Example

Best Practices

Write explicit SEO titles and descriptions — Don't rely on auto-generated fallbacks. Craft each one by hand.

Create platform-specific images — OG images (1200×630) and Twitter images (1200×600) have different dimensions. Design separate assets when you can.

Automate canonical URLs — Generate them from file paths so you don't mess them up manually. Allow frontmatter overrides for syndicated content.

Auto-noindex drafts — Build logic that blocks draft content from indexing regardless of what someone sets manually.

Validate with testing tools — Use Facebook Sharing Debugger, Twitter Card Validator, and Google's Rich Results Test to check your work.

Add structured data for rich snippets — JSON-LD for articles, FAQs, and how-tos can get you those fancy search result cards.

Audit regularly — Run automated checks for missing descriptions, oversized titles, broken images, and missing structured data.

Why SEO Metadata Matters

Complete SEO Frontmatter Example

Title Tag Optimization

Title Tag Best Practices

Framework Implementation

Meta Description

Meta Description Guidelines

Open Graph (og:) Fields

Rendering Open Graph Tags

Twitter Card Fields

Card Type Comparison

Canonical URL

Implementation

Robots Directives

Conditional Robots Based on Draft Status

Structured Data / JSON-LD

Rendering JSON-LD from Frontmatter

Keyword Optimization in Frontmatter

Building a Content Audit Tool

Complete SEO Component

Best Practices

Continue learning this concept

Why SEO Metadata Matters

Complete SEO Frontmatter Example

Title Tag Optimization

Title Tag Best Practices

Framework Implementation

Meta Description

Meta Description Guidelines

Open Graph (og:) Fields

Rendering Open Graph Tags

Twitter Card Fields

Card Type Comparison

Canonical URL

Implementation

Robots Directives

Conditional Robots Based on Draft Status

Structured Data / JSON-LD

Rendering JSON-LD from Frontmatter

Keyword Optimization in Frontmatter

Building a Content Audit Tool

Complete SEO Component

Best Practices

Continue learning this concept