# Documentation SEO Task

**Date:** January 1, 2026  
**Purpose:** Add complete SEO metadata to all documentation pages  
**Priority:** High — required for proper indexing

---

## Reference: Main Page Pattern

Follow the same meta tag structure as the main page (`/`):

```html
<meta name="author" content="Banatie">
<meta name="keywords" content="...">
<meta name="robots" content="index, follow">
<link rel="canonical" href="https://banatie.app/.../">
<link rel="alternate" hreflang="en" href="https://banatie.app/.../">
<link rel="alternate" hreflang="x-default" href="https://banatie.app/.../">
<meta property="og:title" content="...">
<meta property="og:description" content="...">
<meta property="og:url" content="https://banatie.app/.../">
<meta property="og:site_name" content="Banatie">
<meta property="og:locale" content="en_US">
<meta property="og:image" content="https://banatie.app/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Banatie - AI Image Generation API for Developers">
<meta property="og:type" content="article">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="...">
<meta name="twitter:description" content="...">
```

**Key rules:**
- All canonical URLs end with trailing slash: `/docs/` not `/docs`
- Use same OG image for all docs pages: `https://banatie.app/og-image.png`
- og:type should be `article` for docs (not `website`)

---

## Implementation in Next.js

### Option 1: Static Metadata (Recommended for docs)

```tsx
// In each page.tsx
import { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'Page Title | Banatie Docs',
  description: 'Page description...',
  authors: [{ name: 'Banatie' }],
  keywords: ['keyword1', 'keyword2'],
  robots: 'index, follow',
  alternates: {
    canonical: 'https://banatie.app/docs/page/',
    languages: {
      'en': 'https://banatie.app/docs/page/',
      'x-default': 'https://banatie.app/docs/page/',
    },
  },
  openGraph: {
    title: 'Page Title | Banatie Docs',
    description: 'Page description...',
    url: 'https://banatie.app/docs/page/',
    siteName: 'Banatie',
    locale: 'en_US',
    type: 'article',
    images: [
      {
        url: 'https://banatie.app/og-image.png',
        width: 1200,
        height: 630,
        alt: 'Banatie - AI Image Generation API for Developers',
      },
    ],
  },
  twitter: {
    card: 'summary_large_image',
    title: 'Page Title | Banatie Docs',
    description: 'Page description...',
  },
};
```

### Option 2: Shared Metadata in Layout

Create base metadata in `/docs/layout.tsx` and extend in pages:

```tsx
// In layout.tsx - shared defaults
export const metadata: Metadata = {
  authors: [{ name: 'Banatie' }],
  robots: 'index, follow',
  openGraph: {
    siteName: 'Banatie',
    locale: 'en_US',
    type: 'article',
    images: [
      {
        url: 'https://banatie.app/og-image.png',
        width: 1200,
        height: 630,
        alt: 'Banatie - AI Image Generation API for Developers',
      },
    ],
  },
  twitter: {
    card: 'summary_large_image',
  },
};
```

Then in each page, only specify unique fields (title, description, canonical).

---

## Metadata for All 10 Pages

### 1. `/docs/` — Getting Started

```tsx
export const metadata: Metadata = {
  title: 'Getting Started with Banatie API | AI Image Generation',
  description: 'Generate your first AI image in a few simple steps. REST API for production-ready image assets via CDN.',
  keywords: ['banatie api', 'image generation api', 'ai image api tutorial', 'getting started', 'api quickstart'],
  alternates: {
    canonical: 'https://banatie.app/docs/',
    languages: {
      'en': 'https://banatie.app/docs/',
      'x-default': 'https://banatie.app/docs/',
    },
  },
  openGraph: {
    title: 'Getting Started with Banatie API | AI Image Generation',
    description: 'Generate your first AI image in a few simple steps. REST API for production-ready image assets via CDN.',
    url: 'https://banatie.app/docs/',
  },
  twitter: {
    title: 'Getting Started with Banatie API | AI Image Generation',
    description: 'Generate your first AI image in a few simple steps. REST API for production-ready image assets via CDN.',
  },
};
```

### 2. `/docs/generation/` — Image Generation

```tsx
export const metadata: Metadata = {
  title: 'Image Generation Guide | Banatie API Docs',
  description: 'Generate AI images from text prompts. Aspect ratios, prompt templates, reference images, and generation chaining.',
  keywords: ['image generation', 'text to image api', 'ai image prompt', 'aspect ratio', 'reference images'],
  alternates: {
    canonical: 'https://banatie.app/docs/generation/',
    languages: {
      'en': 'https://banatie.app/docs/generation/',
      'x-default': 'https://banatie.app/docs/generation/',
    },
  },
  openGraph: {
    title: 'Image Generation Guide | Banatie API Docs',
    description: 'Generate AI images from text prompts. Aspect ratios, prompt templates, reference images, and generation chaining.',
    url: 'https://banatie.app/docs/generation/',
  },
  twitter: {
    title: 'Image Generation Guide | Banatie API Docs',
    description: 'Generate AI images from text prompts. Aspect ratios, prompt templates, reference images, and generation chaining.',
  },
};
```

### 3. `/docs/images/` — Working with Images

```tsx
export const metadata: Metadata = {
  title: 'Working with Images | Banatie API Docs',
  description: 'Upload, manage, and organize images. CDN delivery, aliases for easy reference, and image management via API.',
  keywords: ['image upload api', 'cdn image delivery', 'image aliases', 'image management', 'organize images'],
  alternates: {
    canonical: 'https://banatie.app/docs/images/',
    languages: {
      'en': 'https://banatie.app/docs/images/',
      'x-default': 'https://banatie.app/docs/images/',
    },
  },
  openGraph: {
    title: 'Working with Images | Banatie API Docs',
    description: 'Upload, manage, and organize images. CDN delivery, aliases for easy reference, and image management via API.',
    url: 'https://banatie.app/docs/images/',
  },
  twitter: {
    title: 'Working with Images | Banatie API Docs',
    description: 'Upload, manage, and organize images. CDN delivery, aliases for easy reference, and image management via API.',
  },
};
```

### 4. `/docs/live-urls/` — Live URLs

```tsx
export const metadata: Metadata = {
  title: 'Live URLs — Generate Images from URL | Banatie API Docs',
  description: 'Generate images directly from URL parameters. No API calls needed — use the URL in img tags. Automatic caching.',
  keywords: ['live url image generation', 'url to image', 'dynamic image generation', 'image from url', 'cached image api'],
  alternates: {
    canonical: 'https://banatie.app/docs/live-urls/',
    languages: {
      'en': 'https://banatie.app/docs/live-urls/',
      'x-default': 'https://banatie.app/docs/live-urls/',
    },
  },
  openGraph: {
    title: 'Live URLs — Generate Images from URL | Banatie API Docs',
    description: 'Generate images directly from URL parameters. No API calls needed — use the URL in img tags. Automatic caching.',
    url: 'https://banatie.app/docs/live-urls/',
  },
  twitter: {
    title: 'Live URLs — Generate Images from URL | Banatie API Docs',
    description: 'Generate images directly from URL parameters. No API calls needed — use the URL in img tags. Automatic caching.',
  },
};
```

### 5. `/docs/authentication/` — Authentication

```tsx
export const metadata: Metadata = {
  title: 'Authentication | Banatie API Docs',
  description: 'How to authenticate with Banatie API using API keys. Get your key and start generating images.',
  keywords: ['api authentication', 'api key', 'banatie api key', 'x-api-key header'],
  alternates: {
    canonical: 'https://banatie.app/docs/authentication/',
    languages: {
      'en': 'https://banatie.app/docs/authentication/',
      'x-default': 'https://banatie.app/docs/authentication/',
    },
  },
  openGraph: {
    title: 'Authentication | Banatie API Docs',
    description: 'How to authenticate with Banatie API using API keys. Get your key and start generating images.',
    url: 'https://banatie.app/docs/authentication/',
  },
  twitter: {
    title: 'Authentication | Banatie API Docs',
    description: 'How to authenticate with Banatie API using API keys. Get your key and start generating images.',
  },
};
```

### 6. `/docs/api/` — API Reference Overview

```tsx
export const metadata: Metadata = {
  title: 'API Reference | Banatie Docs',
  description: 'Complete REST API reference for Banatie. All endpoints, parameters, response formats, and error codes.',
  keywords: ['banatie api reference', 'rest api documentation', 'api endpoints', 'image generation api docs'],
  alternates: {
    canonical: 'https://banatie.app/docs/api/',
    languages: {
      'en': 'https://banatie.app/docs/api/',
      'x-default': 'https://banatie.app/docs/api/',
    },
  },
  openGraph: {
    title: 'API Reference | Banatie Docs',
    description: 'Complete REST API reference for Banatie. All endpoints, parameters, response formats, and error codes.',
    url: 'https://banatie.app/docs/api/',
  },
  twitter: {
    title: 'API Reference | Banatie Docs',
    description: 'Complete REST API reference for Banatie. All endpoints, parameters, response formats, and error codes.',
  },
};
```

### 7. `/docs/api/generations/` — Generations API

```tsx
export const metadata: Metadata = {
  title: 'Generations API | Banatie API Reference',
  description: 'Create, list, update, and delete AI image generations. Full endpoint documentation with examples.',
  keywords: ['generations api', 'create generation', 'image generation endpoint', 'regenerate image api'],
  alternates: {
    canonical: 'https://banatie.app/docs/api/generations/',
    languages: {
      'en': 'https://banatie.app/docs/api/generations/',
      'x-default': 'https://banatie.app/docs/api/generations/',
    },
  },
  openGraph: {
    title: 'Generations API | Banatie API Reference',
    description: 'Create, list, update, and delete AI image generations. Full endpoint documentation with examples.',
    url: 'https://banatie.app/docs/api/generations/',
  },
  twitter: {
    title: 'Generations API | Banatie API Reference',
    description: 'Create, list, update, and delete AI image generations. Full endpoint documentation with examples.',
  },
};
```

### 8. `/docs/api/images/` — Images API

```tsx
export const metadata: Metadata = {
  title: 'Images API | Banatie API Reference',
  description: 'Upload, list, update, and delete images. Manage aliases and access images via CDN.',
  keywords: ['images api', 'upload image api', 'image cdn api', 'image alias api'],
  alternates: {
    canonical: 'https://banatie.app/docs/api/images/',
    languages: {
      'en': 'https://banatie.app/docs/api/images/',
      'x-default': 'https://banatie.app/docs/api/images/',
    },
  },
  openGraph: {
    title: 'Images API | Banatie API Reference',
    description: 'Upload, list, update, and delete images. Manage aliases and access images via CDN.',
    url: 'https://banatie.app/docs/api/images/',
  },
  twitter: {
    title: 'Images API | Banatie API Reference',
    description: 'Upload, list, update, and delete images. Manage aliases and access images via CDN.',
  },
};
```

### 9. `/docs/api/flows/` — Flows API

```tsx
export const metadata: Metadata = {
  title: 'Flows API | Banatie API Reference',
  description: 'Manage generation flows. List, update, and delete flows that group related generations together.',
  keywords: ['flows api', 'generation flow', 'chain generations', 'flow management api'],
  alternates: {
    canonical: 'https://banatie.app/docs/api/flows/',
    languages: {
      'en': 'https://banatie.app/docs/api/flows/',
      'x-default': 'https://banatie.app/docs/api/flows/',
    },
  },
  openGraph: {
    title: 'Flows API | Banatie API Reference',
    description: 'Manage generation flows. List, update, and delete flows that group related generations together.',
    url: 'https://banatie.app/docs/api/flows/',
  },
  twitter: {
    title: 'Flows API | Banatie API Reference',
    description: 'Manage generation flows. List, update, and delete flows that group related generations together.',
  },
};
```

### 10. `/docs/api/live-scopes/` — Live Scopes API

```tsx
export const metadata: Metadata = {
  title: 'Live Scopes API | Banatie API Reference',
  description: 'Manage live URL scopes. Create, configure, and control live image generation endpoints.',
  keywords: ['live scopes api', 'live url management', 'scope limits', 'live generation api'],
  alternates: {
    canonical: 'https://banatie.app/docs/api/live-scopes/',
    languages: {
      'en': 'https://banatie.app/docs/api/live-scopes/',
      'x-default': 'https://banatie.app/docs/api/live-scopes/',
    },
  },
  openGraph: {
    title: 'Live Scopes API | Banatie API Reference',
    description: 'Manage live URL scopes. Create, configure, and control live image generation endpoints.',
    url: 'https://banatie.app/docs/api/live-scopes/',
  },
  twitter: {
    title: 'Live Scopes API | Banatie API Reference',
    description: 'Manage live URL scopes. Create, configure, and control live image generation endpoints.',
  },
};
```

---

## JSON-LD Structured Data

### Create JsonLd Component

Create `/components/seo/JsonLd.tsx`:

```tsx
interface JsonLdProps {
  data: Record<string, unknown>;
}

export function JsonLd({ data }: JsonLdProps) {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
    />
  );
}
```

### BreadcrumbList Schema (All pages)

Add to every docs page:

```tsx
const breadcrumbSchema = {
  '@context': 'https://schema.org',
  '@type': 'BreadcrumbList',
  itemListElement: [
    {
      '@type': 'ListItem',
      position: 1,
      name: 'Home',
      item: 'https://banatie.app/',
    },
    {
      '@type': 'ListItem',
      position: 2,
      name: 'Documentation',
      item: 'https://banatie.app/docs/',
    },
    // Add more levels as needed
  ],
};
```

### TechArticle Schema (Guide pages)

For `/docs/`, `/docs/generation/`, `/docs/images/`, `/docs/live-urls/`, `/docs/authentication/`:

```tsx
const articleSchema = {
  '@context': 'https://schema.org',
  '@type': 'TechArticle',
  headline: 'Page Title',
  description: 'Page description',
  author: {
    '@type': 'Organization',
    name: 'Banatie',
    url: 'https://banatie.app/',
  },
  publisher: {
    '@type': 'Organization',
    name: 'Banatie',
    url: 'https://banatie.app/',
    logo: {
      '@type': 'ImageObject',
      url: 'https://banatie.app/logo.png',
    },
  },
  mainEntityOfPage: {
    '@type': 'WebPage',
    '@id': 'https://banatie.app/docs/page/',
  },
  image: 'https://banatie.app/og-image.png',
};
```

### HowTo Schema (Get Started page)

For `/docs/` specifically — shows steps in search results:

```tsx
const howToSchema = {
  '@context': 'https://schema.org',
  '@type': 'HowTo',
  name: 'How to Generate Your First AI Image with Banatie API',
  description: 'Generate your first AI image in a few simple steps using Banatie REST API.',
  step: [
    {
      '@type': 'HowToStep',
      name: 'Get API Key',
      text: 'Sign up at banatie.app to receive your API key within 24 hours.',
      url: 'https://banatie.app/docs/#get-your-api-key',
    },
    {
      '@type': 'HowToStep',
      name: 'Make API Request',
      text: 'Send a POST request to /api/v1/generations with your prompt.',
      url: 'https://banatie.app/docs/#your-first-image',
    },
    {
      '@type': 'HowToStep',
      name: 'Use Your Image',
      text: 'The response contains a CDN URL ready for production use.',
      url: 'https://banatie.app/docs/#production-ready',
    },
  ],
};
```

### APIReference Schema (API pages)

For `/docs/api/` and sub-pages:

```tsx
const apiSchema = {
  '@context': 'https://schema.org',
  '@type': 'TechArticle',
  headline: 'Banatie API Reference',
  description: 'Complete REST API documentation',
  about: {
    '@type': 'WebAPI',
    name: 'Banatie Image Generation API',
    documentation: 'https://banatie.app/docs/api/',
    provider: {
      '@type': 'Organization',
      name: 'Banatie',
    },
  },
};
```

---

## Implementation Example

Full example for `/docs/page.tsx`:

```tsx
import { Metadata } from 'next';
import { JsonLd } from '@/components/seo/JsonLd';
// ... other imports

export const metadata: Metadata = {
  title: 'Getting Started with Banatie API | AI Image Generation',
  description: 'Generate your first AI image in a few simple steps. REST API for production-ready image assets via CDN.',
  authors: [{ name: 'Banatie' }],
  keywords: ['banatie api', 'image generation api', 'ai image api tutorial', 'getting started', 'api quickstart'],
  robots: 'index, follow',
  alternates: {
    canonical: 'https://banatie.app/docs/',
    languages: {
      'en': 'https://banatie.app/docs/',
      'x-default': 'https://banatie.app/docs/',
    },
  },
  openGraph: {
    title: 'Getting Started with Banatie API | AI Image Generation',
    description: 'Generate your first AI image in a few simple steps. REST API for production-ready image assets via CDN.',
    url: 'https://banatie.app/docs/',
    siteName: 'Banatie',
    locale: 'en_US',
    type: 'article',
    images: [
      {
        url: 'https://banatie.app/og-image.png',
        width: 1200,
        height: 630,
        alt: 'Banatie - AI Image Generation API for Developers',
      },
    ],
  },
  twitter: {
    card: 'summary_large_image',
    title: 'Getting Started with Banatie API | AI Image Generation',
    description: 'Generate your first AI image in a few simple steps. REST API for production-ready image assets via CDN.',
  },
};

const breadcrumbSchema = {
  '@context': 'https://schema.org',
  '@type': 'BreadcrumbList',
  itemListElement: [
    { '@type': 'ListItem', position: 1, name: 'Home', item: 'https://banatie.app/' },
    { '@type': 'ListItem', position: 2, name: 'Documentation', item: 'https://banatie.app/docs/' },
  ],
};

const howToSchema = {
  '@context': 'https://schema.org',
  '@type': 'HowTo',
  name: 'How to Generate Your First AI Image with Banatie API',
  description: 'Generate your first AI image in a few simple steps using Banatie REST API.',
  step: [
    {
      '@type': 'HowToStep',
      name: 'Get API Key',
      text: 'Sign up at banatie.app to receive your API key within 24 hours.',
    },
    {
      '@type': 'HowToStep',
      name: 'Make API Request',
      text: 'Send a POST request to /api/v1/generations with your prompt.',
    },
    {
      '@type': 'HowToStep',
      name: 'Use Your Image',
      text: 'The response contains a CDN URL ready for production use.',
    },
  ],
};

export default function GettingStartedPage() {
  return (
    <>
      <JsonLd data={breadcrumbSchema} />
      <JsonLd data={howToSchema} />
      {/* ... rest of page content */}
    </>
  );
}
```

---

## Checklist

Before marking complete:

- [ ] All 10 pages have metadata export
- [ ] All canonical URLs end with trailing slash
- [ ] All pages use same OG image
- [ ] og:type is "article" (not "website")
- [ ] hreflang alternates present (en + x-default)
- [ ] JsonLd component created
- [ ] BreadcrumbList schema on all pages
- [ ] TechArticle schema on guide pages
- [ ] HowTo schema on /docs/ page
- [ ] Remove 'use client' if not needed (metadata requires server component)

---

## Important Note on 'use client'

Next.js metadata export only works in Server Components. If pages currently have `'use client'`, you need to:

1. Split into Server Component (page with metadata) and Client Component (interactive content)
2. Or move interactive parts to child components

Example structure:
```
/docs/
├── page.tsx           # Server Component with metadata
└── _components/
    └── DocsContent.tsx  # Client Component with interactivity
```

---

**End of Task**
