@zoyth/simple-site-framework 1.0.0

package/docs/features/seo/open-graph.md

@@ -0,0 +1,166 @@
+# Open Graph
+
+Social media preview cards for Facebook, Twitter, LinkedIn, and more.
+
+## Overview
+
+Open Graph tags control how your pages appear when shared on social media. The framework integrates OG tags into the SEOMetaTags component.
+
+## Basic Setup
+
+```typescript
+import { SEOMetaTags } from '@zoyth/simple-site-framework/components';
+
+<SEOMetaTags
+  title="My Page Title"
+  description="Page description"
+  openGraph={{
+    type: 'website',
+    image: 'https://example.com/og-image.jpg',
+    url: 'https://example.com/page',
+    siteName: 'My Company',
+  }}
+/>
+```
+
+## Open Graph Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `string` | Content type: 'website', 'article', 'product' |
+| `image` | `string` | Preview image URL (1200x630px recommended) |
+| `url` | `string` | Canonical URL of the page |
+| `siteName` | `string` | Site name |
+| `locale` | `string` | Content locale (e.g., 'en_US') |
+| `title` | `string` | Override title (defaults to page title) |
+| `description` | `string` | Override description |
+
+## Twitter Cards
+
+```typescript
+<SEOMetaTags
+  title="My Page"
+  description="Description"
+  twitter={{
+    card: 'summary_large_image',
+    site: '@mycompany',
+    creator: '@author',
+    image: 'https://example.com/twitter-card.jpg',
+  }}
+/>
+```
+
+### Card Types
+
+| Type | Description |
+|------|-------------|
+| `summary` | Small square image with title and description |
+| `summary_large_image` | Large image with title and description |
+
+## Image Guidelines
+
+### Open Graph Images
+
+- **Size:** 1200 x 630 pixels
+- **Format:** JPEG or PNG
+- **Max size:** 5MB (Facebook), 5MB (LinkedIn)
+- **Aspect ratio:** 1.91:1
+
+### Twitter Images
+
+- **summary:** 144 x 144 pixels minimum
+- **summary_large_image:** 300 x 157 pixels minimum
+- **Max size:** 5MB
+- **Format:** JPEG, PNG, GIF
+
+## Per-Page Configuration
+
+### Homepage
+
+```typescript
+<SEOMetaTags
+  title="My Company - Professional Services"
+  description="Leading provider of professional services"
+  openGraph={{
+    type: 'website',
+    image: '/images/og-home.jpg',
+    siteName: 'My Company',
+  }}
+/>
+```
+
+### Blog Post
+
+```typescript
+<SEOMetaTags
+  title={post.title}
+  description={post.excerpt}
+  openGraph={{
+    type: 'article',
+    image: post.coverImage,
+    article: {
+      publishedTime: post.publishedAt,
+      author: post.author.name,
+      tags: post.tags,
+    },
+  }}
+/>
+```
+
+### Service Page
+
+```typescript
+<SEOMetaTags
+  title="Tax Preparation Services"
+  description="Professional tax services"
+  openGraph={{
+    type: 'website',
+    image: '/images/og-tax-services.jpg',
+  }}
+/>
+```
+
+## Multi-Language OG Tags
+
+```typescript
+<SEOMetaTags
+  title={getLocalizedString(title, locale)}
+  description={getLocalizedString(description, locale)}
+  openGraph={{
+    type: 'website',
+    locale: locale === 'fr' ? 'fr_CA' : 'en_US',
+    image: `/images/og-${locale}.jpg`,
+  }}
+/>
+```
+
+## Testing
+
+### Facebook Sharing Debugger
+
+Test how your page appears on Facebook:
+- [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/)
+
+### Twitter Card Validator
+
+Test Twitter card rendering:
+- [Twitter Card Validator](https://cards-dev.twitter.com/validator)
+
+### LinkedIn Post Inspector
+
+Test LinkedIn previews:
+- [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/)
+
+## Best Practices
+
+- Always include an og:image - posts with images get more engagement
+- Use high-quality images at recommended dimensions
+- Test on each platform before launch
+- Set unique OG data per page
+- Keep titles under 60 characters
+- Keep descriptions under 155 characters
+
+## See Also
+
+- [Meta Tags](./meta-tags.md)
+- [SEOMetaTags Component](../../components/SEOMetaTags.md)

package/docs/features/seo/robots-txt.md

@@ -0,0 +1,146 @@
+# Robots.txt
+
+Control search engine crawling behavior.
+
+## Overview
+
+The `robots.txt` file tells search engine crawlers which pages to crawl and which to skip.
+
+## Next.js Configuration
+
+Use the Next.js App Router convention:
+
+```typescript
+// app/robots.ts
+import type { MetadataRoute } from 'next';
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+      disallow: ['/api/', '/admin/', '/_next/'],
+    },
+    sitemap: 'https://example.com/sitemap.xml',
+  };
+}
+```
+
+## Common Configurations
+
+### Allow All (Default)
+
+```typescript
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+    },
+    sitemap: 'https://example.com/sitemap.xml',
+  };
+}
+```
+
+### Block Specific Paths
+
+```typescript
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+      disallow: [
+        '/api/',
+        '/admin/',
+        '/private/',
+        '/draft/',
+        '/thank-you',   // Post-conversion pages
+      ],
+    },
+    sitemap: 'https://example.com/sitemap.xml',
+  };
+}
+```
+
+### Different Rules Per Bot
+
+```typescript
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      {
+        userAgent: 'Googlebot',
+        allow: '/',
+        disallow: '/admin/',
+      },
+      {
+        userAgent: 'Bingbot',
+        allow: '/',
+        disallow: '/admin/',
+      },
+      {
+        userAgent: '*',
+        allow: '/',
+        disallow: ['/api/', '/admin/'],
+      },
+    ],
+    sitemap: 'https://example.com/sitemap.xml',
+  };
+}
+```
+
+### Staging Environment
+
+Block all crawling on staging:
+
+```typescript
+export default function robots(): MetadataRoute.Robots {
+  if (process.env.NODE_ENV !== 'production') {
+    return {
+      rules: {
+        userAgent: '*',
+        disallow: '/',
+      },
+    };
+  }
+
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+    },
+    sitemap: 'https://example.com/sitemap.xml',
+  };
+}
+```
+
+## Crawl Delay
+
+Add crawl delay for polite crawling:
+
+```typescript
+rules: {
+  userAgent: '*',
+  allow: '/',
+  crawlDelay: 10, // seconds between requests
+}
+```
+
+## Verification
+
+Visit `http://localhost:3000/robots.txt` to check output.
+
+## Best Practices
+
+- Always include sitemap reference
+- Block API routes and admin pages
+- Block staging/preview environments entirely
+- Don't block CSS/JS files (search engines need them for rendering)
+- Use noindex meta tag for pages that should appear in sitemap but not search
+- Test with Google Search Console
+
+## See Also
+
+- [Sitemaps](./sitemaps.md)
+- [Meta Tags](./meta-tags.md)

package/docs/features/seo/sitemaps.md

@@ -0,0 +1,162 @@
+# Sitemaps
+
+XML sitemap generation for search engine discovery.
+
+## Overview
+
+Sitemaps help search engines discover and index all pages on your site. The framework supports sitemap generation for multi-language sites.
+
+## Next.js Sitemap
+
+Use the Next.js App Router sitemap convention:
+
+```typescript
+// app/sitemap.ts
+import type { MetadataRoute } from 'next';
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const baseUrl = 'https://example.com';
+
+  return [
+    {
+      url: baseUrl,
+      lastModified: new Date(),
+      changeFrequency: 'weekly',
+      priority: 1,
+    },
+    {
+      url: `${baseUrl}/about`,
+      lastModified: new Date(),
+      changeFrequency: 'monthly',
+      priority: 0.8,
+    },
+    {
+      url: `${baseUrl}/services`,
+      lastModified: new Date(),
+      changeFrequency: 'monthly',
+      priority: 0.8,
+    },
+    {
+      url: `${baseUrl}/contact`,
+      lastModified: new Date(),
+      changeFrequency: 'yearly',
+      priority: 0.5,
+    },
+  ];
+}
+```
+
+## Multi-Language Sitemaps
+
+Include locale alternates:
+
+```typescript
+// app/sitemap.ts
+import type { MetadataRoute } from 'next';
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const baseUrl = 'https://example.com';
+  const locales = ['en', 'fr', 'es'];
+  const pages = ['', '/about', '/services', '/contact'];
+
+  return pages.flatMap(page =>
+    locales.map(locale => ({
+      url: `${baseUrl}${locale === 'en' ? '' : `/${locale}`}${page}`,
+      lastModified: new Date(),
+      alternates: {
+        languages: Object.fromEntries(
+          locales.map(l => [
+            l,
+            `${baseUrl}${l === 'en' ? '' : `/${l}`}${page}`,
+          ])
+        ),
+      },
+    }))
+  );
+}
+```
+
+## Dynamic Sitemaps
+
+Generate from data sources:
+
+```typescript
+// app/sitemap.ts
+export default async function sitemap(): MetadataRoute.Sitemap {
+  const baseUrl = 'https://example.com';
+
+  // Fetch dynamic pages
+  const posts = await getBlogPosts();
+  const services = await getServices();
+
+  const staticPages = [
+    { url: baseUrl, priority: 1 },
+    { url: `${baseUrl}/about`, priority: 0.8 },
+  ];
+
+  const blogPages = posts.map(post => ({
+    url: `${baseUrl}/blog/${post.slug}`,
+    lastModified: post.updatedAt,
+    priority: 0.6,
+  }));
+
+  const servicePages = services.map(service => ({
+    url: `${baseUrl}/services/${service.slug}`,
+    lastModified: service.updatedAt,
+    priority: 0.8,
+  }));
+
+  return [...staticPages, ...blogPages, ...servicePages];
+}
+```
+
+## Sitemap Index
+
+For large sites, split into multiple sitemaps:
+
+```typescript
+// app/sitemap.ts
+export async function generateSitemaps() {
+  const totalPages = await getPageCount();
+  const sitemapsNeeded = Math.ceil(totalPages / 50000);
+
+  return Array.from({ length: sitemapsNeeded }, (_, i) => ({ id: i }));
+}
+
+export default async function sitemap({ id }: { id: number }) {
+  const start = id * 50000;
+  const pages = await getPages(start, 50000);
+
+  return pages.map(page => ({
+    url: `https://example.com${page.path}`,
+    lastModified: page.updatedAt,
+  }));
+}
+```
+
+## Verification
+
+### Google Search Console
+
+1. Submit sitemap URL in Search Console
+2. Monitor indexing status
+3. Check for errors
+
+### Test Locally
+
+Visit `http://localhost:3000/sitemap.xml` to verify output.
+
+## Best Practices
+
+- Include all important pages
+- Set accurate `lastModified` dates
+- Use appropriate `priority` values (0.0 to 1.0)
+- Keep sitemaps under 50,000 URLs
+- Update sitemap when content changes
+- Submit sitemap to Google Search Console
+
+## See Also
+
+- [Existing Sitemap Documentation](../../SITEMAP.md)
+- [Robots.txt](./robots-txt.md)
+- [Canonical URLs](./canonical-urls.md)

package/docs/features/seo/structured-data.md

@@ -0,0 +1,166 @@
+# Structured Data
+
+Add Schema.org JSON-LD markup for rich search results.
+
+## StructuredData Component
+
+```typescript
+import { StructuredData } from '@zoyth/simple-site-framework/components';
+
+<StructuredData
+  data={{
+    '@type': 'Organization',
+    name: 'My Company',
+    url: 'https://example.com',
+    logo: 'https://example.com/logo.png',
+  }}
+/>
+```
+
+## Common Schema Types
+
+### Organization
+
+```typescript
+<StructuredData
+  data={{
+    '@type': 'Organization',
+    name: 'My Company',
+    url: 'https://example.com',
+    logo: 'https://example.com/logo.png',
+    contactPoint: {
+      '@type': 'ContactPoint',
+      telephone: '+1-555-123-4567',
+      contactType: 'customer service',
+    },
+    sameAs: [
+      'https://facebook.com/mycompany',
+      'https://twitter.com/mycompany',
+      'https://linkedin.com/company/mycompany',
+    ],
+  }}
+/>
+```
+
+### LocalBusiness
+
+```typescript
+<StructuredData
+  data={{
+    '@type': 'LocalBusiness',
+    name: 'My Dental Practice',
+    image: 'https://example.com/photo.jpg',
+    address: {
+      '@type': 'PostalAddress',
+      streetAddress: '123 Main St',
+      addressLocality: 'Montreal',
+      addressRegion: 'QC',
+      postalCode: 'H1A 1A1',
+      addressCountry: 'CA',
+    },
+    telephone: '+1-555-123-4567',
+    openingHoursSpecification: [
+      {
+        '@type': 'OpeningHoursSpecification',
+        dayOfWeek: ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'],
+        opens: '09:00',
+        closes: '17:00',
+      },
+    ],
+  }}
+/>
+```
+
+### Service
+
+```typescript
+<StructuredData
+  data={{
+    '@type': 'Service',
+    name: 'Tax Preparation',
+    description: 'Professional tax preparation for individuals and businesses',
+    provider: {
+      '@type': 'Organization',
+      name: 'My Accounting Firm',
+    },
+    areaServed: {
+      '@type': 'City',
+      name: 'Montreal',
+    },
+  }}
+/>
+```
+
+### FAQ
+
+```typescript
+<StructuredData
+  data={{
+    '@type': 'FAQPage',
+    mainEntity: [
+      {
+        '@type': 'Question',
+        name: 'What services do you offer?',
+        acceptedAnswer: {
+          '@type': 'Answer',
+          text: 'We offer accounting, tax, and advisory services.',
+        },
+      },
+      {
+        '@type': 'Question',
+        name: 'Where are you located?',
+        acceptedAnswer: {
+          '@type': 'Answer',
+          text: 'We are located in downtown Montreal.',
+        },
+      },
+    ],
+  }}
+/>
+```
+
+### BreadcrumbList
+
+```typescript
+<StructuredData
+  data={{
+    '@type': 'BreadcrumbList',
+    itemListElement: [
+      { '@type': 'ListItem', position: 1, name: 'Home', item: 'https://example.com/' },
+      { '@type': 'ListItem', position: 2, name: 'Services', item: 'https://example.com/services' },
+      { '@type': 'ListItem', position: 3, name: 'Tax', item: 'https://example.com/services/tax' },
+    ],
+  }}
+/>
+```
+
+## Testing
+
+### Google Rich Results Test
+
+Test your structured data:
+1. Go to [Rich Results Test](https://search.google.com/test/rich-results)
+2. Enter your page URL
+3. Verify no errors or warnings
+
+### Schema Markup Validator
+
+Validate Schema.org compliance:
+1. Go to [Schema Markup Validator](https://validator.schema.org/)
+2. Enter URL or paste JSON-LD
+3. Check for errors
+
+## Best Practices
+
+- Add Organization schema to homepage
+- Add LocalBusiness for local service businesses
+- Add FAQ schema to FAQ pages
+- Add BreadcrumbList for navigation
+- Keep data accurate and up-to-date
+- Don't add schema for content not visible on the page
+
+## See Also
+
+- [Existing Structured Data Documentation](../../STRUCTURED-DATA.md)
+- [StructuredData Component](../../components/StructuredData.md)
+- [Meta Tags](./meta-tags.md)