pSEO Dynamic Metadata

Implement a metadata system that generates unique, accurate SEO tags for every programmatic page.

Core Principles

1. •Every page gets unique metadata: No two pages share the same title or description
2. •Data-driven generation: Metadata is constructed from structured content fields, not hardcoded
3. •Canonical by default: Every page declares its canonical URL
4. •Social-ready: Open Graph and Twitter cards are complete on every page
5. •Framework-native: Use the framework's built-in metadata API

Implementation Steps

1. Create the Metadata Generator

Build a centralized function that constructs metadata from page data:

Next.js App Router pattern:

// lib/metadata.ts
import type { Metadata } from "next";

export function generatePageMetadata(data: PageData, baseUrl: string): Metadata {
  const title = buildTitle(data);
  const description = buildDescription(data);
  const canonicalUrl = `${baseUrl}${data.canonicalPath}`;

  return {
    title,
    description,
    alternates: { canonical: canonicalUrl },
    openGraph: {
      title,
      description,
      url: canonicalUrl,
      type: "article",
      siteName: "Site Name",
      // images: [{ url, width, height, alt }],
    },
    twitter: {
      card: "summary_large_image",
      title,
      description,
      // images: [url],
    },
  };
}

2. Build Title Construction Logic

Titles must be:

• •Unique across all pages (validate with pseo-quality-guard)
• •50-60 characters target length (hard cap at 70)
• •Front-loaded with the primary keyword
• •Multi-dimensional: Use 2+ data fields to construct, not just one variable

function buildTitle(data: PageData): string {
  // Combine multiple data dimensions
  // e.g., "{primary keyword} - {differentiator} | {brand}"
  // NOT just "{keyword} | Brand" for every page
}

3. Build Description Construction Logic

Descriptions must be:

• •Unique across all pages
• •150-160 characters target length
• •Action-oriented: Include a value proposition or call to action
• •Keyword-inclusive: Naturally incorporate the page's target keyword

4. Implement Canonical URLs

• •Every page must set a self-referencing canonical URL
• •Use absolute URLs (include protocol and domain)
• •Canonicals must match the actual URL path exactly (no trailing slash mismatches)
• •For paginated content, each page gets its own canonical
• •If a page has query parameters, the canonical should point to the clean URL

5. Configure Open Graph Tags

Required OG tags for every pSEO page:

• •og:title - Can differ from the HTML title (no brand suffix needed)
• •og:description - Can differ from meta description
• •og:url - Must match canonical
• •og:type - Usually "article" for content pages, "website" for hubs
• •og:site_name - Consistent across all pages
• •og:image - Page-specific or category-specific image with alt text
• •og:locale - Language/locale setting

6. Configure Twitter Card Tags

Required Twitter tags:

• •twitter:card - Usually "summary_large_image"
• •twitter:title - Can match OG title
• •twitter:description - Can match OG description
• •twitter:image - Can match OG image

7. Add Supplementary Meta Tags

Where appropriate:

• •robots: Default to index, follow; set noindex for thin/utility pages
• •author: If content has an author
• •article:published_time / article:modified_time: For article-type pages

8. Export Metadata in Page Files

Wire the metadata generator into every page route:

// app/[category]/[slug]/page.tsx
export async function generateMetadata({ params }): Promise<Metadata> {
  const data = await getPageData(params.slug);
  if (!data) return {};
  return generatePageMetadata(data, process.env.NEXT_PUBLIC_BASE_URL);
}

9. Internationalization (i18n) Metadata

For multi-language pSEO sites, add language-specific metadata:

• •hreflang tags: Declare all language variants of each page. Every page must link to all its translations including itself.
  typescript

  alternates: {
    canonical: canonicalUrl,
    languages: {
      "en": `${baseUrl}/en/${data.canonicalPath}`,
      "de": `${baseUrl}/de/${data.canonicalPath}`,
      "x-default": `${baseUrl}/en/${data.canonicalPath}`,
    },
  }
  

• •x-default: Always include an x-default hreflang pointing to the primary language or a language selector page
• •Canonical per language: Each language version gets its own canonical (e.g., /en/service/slug and /de/service/slug are each self-canonical)
• •og:locale: Set to the page's language (e.g., en_US, de_DE)
• •og:locale:alternate: List all other available locales
• •URL structure: Use path prefixes (/en/, /de/), not query params or subdomains, for best crawlability
• •Title and description: Must be translated, not just the body. Templated metadata in the target language.

Metadata Validation Rules

Run these checks (or integrate with pseo-quality-guard):

• •No two pages produce the same title
• •No two pages produce the same description
• •All titles are between 30-70 characters
• •All descriptions are between 100-170 characters
• •All canonical URLs resolve to 200 status
• •All OG tags are present on every page
• •No page is missing metadata entirely

File Organization

lib/
  metadata.ts          # generatePageMetadata() and helpers
  metadata.test.ts     # validation tests for metadata generation

Relationship to Other Skills

• •Depends on: pseo-data (content models provide metadata fields)
• •Works with: pseo-templates (metadata is exported alongside page components)
• •Validated by: pseo-quality-guard (checks uniqueness and completeness)