Site-Wide SEO Optimization Implementation Plan

This document outlines the plan for implementing comprehensive SEO metadata across the site using Next.js's Metadata API. Currently, we have basic metadata but we're missing key fields that affect search rankings and social media sharing.

Current State

Right now we have two separate metadata systems:

• Next.js metadata - Exists in layout.tsx with basic title and description, but most pages don't override it
• Custom PostMeta - Our own metadata system for content organization (routeMetadata export)

The problem: Next.js doesn't read our PostMeta for SEO. We need to export both so our content system works AND search engines get proper metadata.

What We're Missing

• OpenGraph metadata - For rich previews on Facebook, LinkedIn, Discord, Slack
• Twitter Card metadata - For Twitter/X link previews
• Page-specific metadata - Most pages use the generic site-level metadata instead of their own
• Canonical URLs - To avoid duplicate content issues

Implementation Plan

Phase 1: High-Priority Pages

Start with pages that are most likely to be shared or searched:

• /about-me - Already updated with description, needs OpenGraph + Twitter metadata
• / (home page) - Needs dedicated metadata export
• /my-stack - Good SEO target for "react developer" searches

Phase 2: Content Pages

All blog posts and docs should have rich metadata for sharing:

• Add Next.js metadata export to all TSX content files
• Keep PostMeta for our content system
• Derive Next.js metadata from PostMeta to avoid duplication

Phase 3: Automation

Make metadata generation automatic:

• Update content creation script to generate both PostMeta and Next.js metadata
• Create a helper function to convert PostMeta → Metadata
• Add linting/validation to ensure all pages have proper metadata

Metadata Structure Template

Here's what each page should export:

.ts

import type { Metadata } from 'next'
import type { PostMeta } from '@/types/post'

// Your custom metadata (for content system)
export const routeMetadata: PostMeta = {
  title: 'Page Title - Jay Griffin',
  slug: 'page-slug',
  date: '2026-02-09T00:00:00Z',
  author: ['Jay Griffin'],
  description: 'Clear description of what this page is about',
  tags: ['relevant', 'tags'],
  path: '/page-slug',
}

// Next.js metadata (for actual SEO)
export const metadata: Metadata = {
  title: routeMetadata.title,
  description: routeMetadata.description,

  openGraph: {
    title: routeMetadata.title,
    description: routeMetadata.description,
    url: `https://jaygriff.com${routeMetadata.path}`,
    siteName: 'Jay Griffin',
    type: 'article',
    images: [
      {
        url: 'https://jaygriff.com/og-image.jpg',
        width: 1200,
        height: 630,
        alt: routeMetadata.title,
      },
    ],
  },

  twitter: {
    card: 'summary_large_image',
    title: routeMetadata.title,
    description: routeMetadata.description,
    images: ['https://jaygriff.com/twitter-image.jpg'],
  },
}

OpenGraph Image Generation

We need to create or generate Open Graph images (1200x630px) for social sharing. Options:

• Dynamic generation - Use Next.js ImageResponse API to generate OG images at build time
• Static images - Create a template in Figma and generate manually
• Hybrid - Default generic image, custom images for key pages

SEO Metadata Fields Reference

Basic Metadata

.ts

{
  title: 'Page Title',              // Browser tab, search results
  description: 'Meta description',   // Search result snippet
  keywords: ['array', 'of', 'terms'], // Mostly ignored by modern search engines
  authors: [{ name: 'Jay Griffin' }],
  robots: 'index, follow',           // Crawling instructions
  alternates: {
    canonical: 'https://jaygriff.com/path', // Preferred URL
  }
}

OpenGraph Metadata

.ts

openGraph: {
  title: 'Page Title',
  description: 'Description for social media',
  url: 'https://jaygriff.com/path',
  siteName: 'Jay Griffin',
  locale: 'en_US',
  type: 'website',
  images: [
    {
      url: 'https://jaygriff.com/og-image.jpg',
      width: 1200,
      height: 630,
      alt: 'Image description',
    },
  ],
}

Twitter Card Metadata

.ts

twitter: {
  card: 'summary_large_image',
  title: 'Page Title',
  description: 'Description for Twitter',
  creator: '@yourhandle',
  images: ['https://jaygriff.com/twitter-image.jpg'],
}

Testing & Validation

After implementing, test with these tools:

• OpenGraph Preview Tool - See how links look on social media
• Twitter Card Validator - Test Twitter previews
• Google Rich Results Test - Validate structured data
• View source - Manually check meta tags are present in HTML

Success Metrics

• Every page has unique title and description
• Links shared on social media show rich previews with image
• Search results show accurate, compelling descriptions
• No duplicate content issues (canonical URLs set)
• "Jay Griffin developer" searches reliably surface the site

Resources

• Next.js Metadata API Documentation
• Open Graph Protocol
• Twitter Card Documentation

Implementation Checklist

• Update about-me page with full metadata (OpenGraph + Twitter)
• Update home page with dedicated metadata
• Update my-stack page with SEO-optimized metadata
• Create/generate OpenGraph images (1200x630)
• Add metadata helper function (PostMeta → Metadata)
• Update content creation script to include Next.js metadata
• Audit all existing pages and add metadata where missing
• Test with social media preview tools
• Add canonical URLs to prevent duplicate content
• Monitor search console for improvements

Notes

This is a one-time implementation effort with long-term benefits. Once the infrastructure is in place, new content automatically gets proper metadata through the content creation system. The focus should be on making it automatic so we never think about it again.