sanity-plugin-seofields 1.0.8 → 1.0.10

package/README.md

@@ -130,14 +130,14 @@ export default defineType({
 
 ## 🎨 Available Schema Types
 
-| Type            | Description               | Use Case                         |
-| --------------- | ------------------------- | -------------------------------- |
-| `seoFields`     | Complete SEO package      | Main SEO fields for any document |
-| `openGraph`     | Open Graph meta tags      | Social media sharing             |
-| `twitter`       | X (Formerly Twitter) Card settings | X-specific optimization    |
-| `metaTag`       | Custom meta attributes    | Advanced meta tag management     |
-| `metaAttribute` | Individual meta attribute | Building custom meta tags        |
-| `robots`        | Search engine directives  | Control indexing and crawling    |
+| Type            | Description                        | Use Case                         |
+| --------------- | ---------------------------------- | -------------------------------- |
+| `seoFields`     | Complete SEO package               | Main SEO fields for any document |
+| `openGraph`     | Open Graph meta tags               | Social media sharing             |
+| `twitter`       | X (Formerly Twitter) Card settings | X-specific optimization          |
+| `metaTag`       | Custom meta attributes             | Advanced meta tag management     |
+| `metaAttribute` | Individual meta attribute          | Building custom meta tags        |
+| `robots`        | Search engine directives           | Control indexing and crawling    |
 
 ## 🔧 Configuration Options
 
@@ -189,14 +189,14 @@ export default defineConfig({
       // Hide sitewide fields on specific content types
       fieldVisibility: {
         page: {
-          hiddenFields: ['openGraphSiteName', 'twitterSite']
+          hiddenFields: ['openGraphSiteName', 'twitterSite'],
         },
         post: {
-          hiddenFields: ['openGraphSiteName', 'twitterSite']
-        }
+          hiddenFields: ['openGraphSiteName', 'twitterSite'],
+        },
       },
       // Or hide fields globally
-      defaultHiddenFields: ['openGraphSiteName', 'twitterSite']
+      defaultHiddenFields: ['openGraphSiteName', 'twitterSite'],
     } satisfies SeoFieldsPluginConfig),
   ],
 })
@@ -220,53 +220,48 @@ Each field in the `fieldOverrides` object can have:
 
 **Available field keys:**
 
-- `title`
-- `description`
-- `canonicalUrl`
-- `metaImage`
-- `keywords`
-- `metaAttributes`
+- `title`, `description`, `canonicalUrl`, `metaImage`, `keywords`, `metaAttributes`, `robots`
+- `openGraphUrl`, `openGraphTitle`, `openGraphDescription`, `openGraphSiteName`, `openGraphType`, `openGraphImage`
+- `twitterCard`, `twitterSite`, `twitterCreator`, `twitterTitle`, `twitterDescription`, `twitterImage`
 
 #### Field Visibility Configuration
 
 Control which fields are visible on different content types. You can hide any SEO field on any post type:
 
 **Available field keys:**
-- `title` - Meta Title field
-- `description` - Meta Description field
-- `canonicalUrl` - Canonical URL field
-- `metaImage` - Meta Image field
-- `keywords` - Keywords field
-- `metaAttributes` - Custom Meta Attributes field
-- `robots` - Robots Settings field
-- `openGraphSiteName` - Open Graph Site Name field (sitewide)
-- `twitterSite` - X (Formerly Twitter) Site Handle field (sitewide)
+
+- `title`, `description`, `canonicalUrl`, `metaImage`, `keywords`, `metaAttributes`, `robots`
+- `openGraphUrl`, `openGraphTitle`, `openGraphDescription`, `openGraphSiteName`, `openGraphType`, `openGraphImage`
+- `twitterCard`, `twitterSite`, `twitterCreator`, `twitterTitle`, `twitterDescription`, `twitterImage`
+
+> ℹ️ Hiding `openGraphImage` or `twitterImage` also hides their URL and type variants to keep the editor experience consistent.
 
 **Example configurations:**
 
 ```typescript
 // Hide fields globally
 seofields({
-  defaultHiddenFields: ['openGraphSiteName', 'twitterSite', 'keywords']
+  defaultHiddenFields: ['openGraphSiteName', 'twitterSite', 'keywords'],
 })
 
 // Hide fields on specific content types
 seofields({
   fieldVisibility: {
     page: {
-      hiddenFields: ['openGraphSiteName', 'twitterSite', 'keywords']
+      hiddenFields: ['openGraphSiteName', 'twitterSite', 'keywords'],
     },
     post: {
-      hiddenFields: ['openGraphSiteName', 'metaAttributes']
+      hiddenFields: ['openGraphSiteName', 'metaAttributes'],
     },
     product: {
-      hiddenFields: ['canonicalUrl', 'robots']
-    }
-  }
+      hiddenFields: ['canonicalUrl', 'robots'],
+    },
+  },
 })
 ```
 
 This is particularly useful when you want to:
+
 - Manage sitewide settings (like site name and X handle) in a dedicated Site Settings document
 - Simplify the editing experience by hiding fields that aren't relevant for certain content types
 - Create different SEO workflows for different content types
@@ -285,6 +280,30 @@ This is particularly useful when you want to:
 - **Purpose**: Search result descriptions
 - **Best Practice**: Compelling summary with keywords
 
+#### Canonical URL
+
+- **Format**: Must include protocol (https://)
+- **Purpose**: Signals the preferred URL when duplicate or paginated content exists
+- **Best Practice**: Mirror the resolved frontend route exactly to avoid mismatched indexing
+
+#### Meta Image
+
+- **Recommended Size**: 1200x630px minimum 600x315px
+- **Purpose**: Default share image when Open Graph/Twitter images are absent
+- **Best Practice**: Provide descriptive alt text and keep file size under 5MB
+
+#### Meta Attributes
+
+- **Structure**: Key/value pairs or key/image pairs
+- **Purpose**: Add bespoke `<meta>` tags (for example `theme-color`, `author`, verification tokens)
+- **Best Practice**: Avoid duplicating tags already generated elsewhere to limit head bloat
+
+#### Keywords
+
+- **Type**: Array of short strings
+- **Purpose**: Editorial helper; not surfaced automatically to search engines
+- **Best Practice**: Keep entries concise (1-3 words) and limit to high-intent topics
+
 #### Open Graph Image
 
 - **Recommended Size**: 1200x630px
@@ -299,6 +318,16 @@ This is particularly useful when you want to:
 - **Best Practice**: Use the preferred URL for the page to avoid duplicate content issues
 - **Required**: Should match the actual page URL for consistency
 
+#### Open Graph Site Name
+
+- **Purpose**: Displays publisher name on share previews
+- **Best Practice**: Keep consistent with brand name used across marketing channels
+
+#### Open Graph Type
+
+- **Options**: `website`, `article`, `profile`, `book`, `music`, `video`, `product`
+- **Best Practice**: Pick the narrowest type applicable to unlock platform-specific rendering
+
 #### X (Formerly Twitter) Card Image
 
 - **Summary Card**: Minimum 120x120px
@@ -312,81 +341,22 @@ This is particularly useful when you want to:
 - **Usage**: Identifies the individual author of the content
 - **Best Practice**: Use actual X handles for proper attribution
 
-## 💻 TypeScript Usage
+#### X (Formerly Twitter) Card Type
 
-The plugin includes full TypeScript support:
+- **Options**: `summary`, `summary_large_image`, `app`, `player`
+- **Best Practice**: Use `summary_large_image` for rich media, fall back to `summary` when imagery is square or minimal
 
-```typescript
-import type {
-  SeoFields,
-  OpenGraphSettings,
-  TwitterCardSettings,
-  SeoFieldsPluginConfig,
-} from 'sanity-plugin-seofields'
-
-// Plugin configuration
-const pluginConfig: SeoFieldsPluginConfig = {
-  seoPreview: true,
-  fields: {
-    title: {
-      title: 'Page Title',
-      description: 'The main title for search engines',
-    },
-    description: {
-      title: 'Meta Description',
-      description: 'Brief description for search results',
-    },
-  },
-}
+#### X (Formerly Twitter) Site Handle
 
-// Use in your document interfaces
-interface PageDocument {
-  _type: 'page'
-  title: string
-  seo?: SeoFields
-}
+- **Purpose**: Publisher attribution when multiple authors contribute
+- **Format**: X handle with @ symbol (e.g., @brand)
+- **Best Practice**: Configure once in site settings and hide on document types that inherit it
 
-// Type-safe field access
-const seoData: SeoFields = {
-  _type: 'seoFields',
-  title: 'My Page Title',
-  description: 'A great page description',
-  openGraph: {
-    _type: 'openGraph',
-    title: 'Social Media Title',
-    description: 'Social media description',
-    url: 'https://example.com/page',
-    type: 'website',
-  },
-  twitter: {
-    _type: 'twitter',
-    card: 'summary_large_image',
-    site: '@example',
-    creator: '@creator',
-    title: 'Twitter Title',
-    description: 'Twitter description',
-  },
-}
-```
+#### Robots Settings
 
-### Available Types
-
-```typescript
-import type {
-  SeoFields,
-  SeoFieldsPluginConfig,
-  SeoFieldConfig,
-  SeoFieldKeys,
-  SitewideFieldKeys,
-  FieldVisibilityConfig,
-  OpenGraphSettings,
-  TwitterCardSettings,
-  MetaAttribute,
-  MetaTag,
-  RobotsSettings,
-  SanityImage,
-} from 'sanity-plugin-seofields'
-```
+- **Options**: `noIndex`, `noFollow`
+- **Purpose**: Control whether pages are indexed or links followed by crawlers
+- **Best Practice**: Only enable when intentionally blocking content (for example gated pages or previews)
 
 ## 🎛️ Field Visibility Feature
 
@@ -399,15 +369,15 @@ The field visibility feature allows you to hide any SEO field on specific conten
 seofields({
   fieldVisibility: {
     page: {
-      hiddenFields: ['openGraphSiteName', 'twitterSite', 'keywords']
+      hiddenFields: ['openGraphSiteName', 'twitterSite', 'keywords'],
     },
     post: {
-      hiddenFields: ['openGraphSiteName', 'metaAttributes']
+      hiddenFields: ['openGraphSiteName', 'metaAttributes'],
     },
     product: {
-      hiddenFields: ['canonicalUrl', 'robots']
-    }
-  }
+      hiddenFields: ['canonicalUrl', 'robots'],
+    },
+  },
 })
 ```
 
@@ -475,45 +445,28 @@ defineField({
 
 ### Next.js Example
 
-```typescript
-import {SeoFields} from 'sanity-plugin-seofields'
+```tsx
 import Head from 'next/head'
 
-interface SEOProps {
-  seo?: SeoFields
-}
-
-export function SEOHead({seo}: SEOProps) {
+export function SEOHead({seo}) {
   if (!seo) return null
 
   return (
     <Head>
       {seo.title && <title>{seo.title}</title>}
-      {seo.description && (
-        <meta name="description" content={seo.description} />
-      )}
+      {seo.description && <meta name="description" content={seo.description} />}
 
       {/* Open Graph */}
-      {seo.openGraph?.title && (
-        <meta property="og:title" content={seo.openGraph.title} />
-      )}
+      {seo.openGraph?.title && <meta property="og:title" content={seo.openGraph.title} />}
       {seo.openGraph?.description && (
         <meta property="og:description" content={seo.openGraph.description} />
       )}
-      {seo.openGraph?.url && (
-        <meta property="og:url" content={seo.openGraph.url} />
-      )}
+      {seo.openGraph?.url && <meta property="og:url" content={seo.openGraph.url} />}
 
       {/* Twitter */}
-      {seo.twitter?.card && (
-        <meta name="twitter:card" content={seo.twitter.card} />
-      )}
-      {seo.twitter?.site && (
-        <meta name="twitter:site" content={seo.twitter.site} />
-      )}
-      {seo.twitter?.creator && (
-        <meta name="twitter:creator" content={seo.twitter.creator} />
-      )}
+      {seo.twitter?.card && <meta name="twitter:card" content={seo.twitter.card} />}
+      {seo.twitter?.site && <meta name="twitter:site" content={seo.twitter.site} />}
+      {seo.twitter?.creator && <meta name="twitter:creator" content={seo.twitter.creator} />}
 
       {/* Robots */}
       {seo.robots?.noIndex && <meta name="robots" content="noindex" />}
@@ -528,24 +481,17 @@ export function SEOHead({seo}: SEOProps) {
 
 ### React/Gatsby Example
 
-```typescript
+```tsx
 import {Helmet} from 'react-helmet'
-import {SeoFields} from 'sanity-plugin-seofields'
 
-interface SEOProps {
-  seo?: SeoFields
-}
-
-export function SEO({seo}: SEOProps) {
+export function SEO({seo}) {
   return (
     <Helmet>
       <title>{seo?.title}</title>
       <meta name="description" content={seo?.description} />
 
       {/* Keywords */}
-      {seo?.keywords && (
-        <meta name="keywords" content={seo.keywords.join(', ')} />
-      )}
+      {seo?.keywords && <meta name="keywords" content={seo.keywords.join(', ')} />}
 
       {/* Open Graph */}
       <meta property="og:title" content={seo?.openGraph?.title} />
@@ -554,15 +500,9 @@ export function SEO({seo}: SEOProps) {
       <meta property="og:type" content={seo?.openGraph?.type || 'website'} />
 
       {/* Twitter */}
-      {seo?.twitter?.card && (
-        <meta name="twitter:card" content={seo.twitter.card} />
-      )}
-      {seo?.twitter?.site && (
-        <meta name="twitter:site" content={seo.twitter.site} />
-      )}
-      {seo?.twitter?.creator && (
-        <meta name="twitter:creator" content={seo.twitter.creator} />
-      )}
+      {seo?.twitter?.card && <meta name="twitter:card" content={seo.twitter.card} />}
+      {seo?.twitter?.site && <meta name="twitter:site" content={seo.twitter.site} />}
+      {seo?.twitter?.creator && <meta name="twitter:creator" content={seo.twitter.creator} />}
     </Helmet>
   )
 }
@@ -585,25 +525,6 @@ import seofields from 'sanity-plugin-seofields'
 - `metaAttribute` - Individual meta attribute
 - `robots` - Search engine robots settings
 
-### TypeScript Types
-
-All types are exported from the main module for use in your project.
-
-### Migration Utilities
-
-The plugin includes utilities for migrating existing data from old formats:
-
-```typescript
-import { 
-  migrateSeoFields, 
-  generateMigrationScript, 
-  needsMigration,
-  normalizeValue 
-} from 'sanity-plugin-seofields'
-```
-
-For detailed migration instructions, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md).
-
 ## 🤝 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.d.mts

@@ -1,82 +1,14 @@
 import {ObjectDefinition} from 'sanity'
 import {Plugin as Plugin_2} from 'sanity'
 import {PreviewConfig} from 'sanity'
+import {SchemaTypeDefinition} from 'sanity'
 
 export declare type AllFieldKeys = SeoFieldKeys | openGraphFieldKeys | twitterFieldKeys
 
-export declare function allSchemas(config?: SeoFieldsPluginConfig): (
-  | ({
-      type: 'object'
-      name: 'twitter'
-    } & Omit<ObjectDefinition, 'preview'> & {
-        preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
-      })
-  | ({
-      type: 'object'
-      name: 'seoFields'
-    } & Omit<ObjectDefinition, 'preview'> & {
-        preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
-      })
-  | ({
-      type: 'object'
-      name: 'metaAttribute'
-    } & Omit<ObjectDefinition, 'preview'> & {
-        preview?:
-          | PreviewConfig<
-              {
-                attributeName: string
-                attributeValueString: string
-                attributeValueImage: string
-              },
-              {
-                attributeName: string
-                attributeValueString: string
-                attributeValueImage: any
-              }
-            >
-          | undefined
-      })
-  | ({
-      type: 'object'
-      name: 'openGraph'
-    } & Omit<ObjectDefinition, 'preview'> & {
-        preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
-      })
-  | ({
-      type: 'object'
-      name: 'robots'
-    } & Omit<ObjectDefinition, 'preview'> & {
-        preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
-      })
-  | ({
-      type: 'object'
-      name: 'metaTag'
-    } & Omit<ObjectDefinition, 'preview'> & {
-        preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
-      })
-)[]
-
-export declare const defaultSeoValidationRules: SeoValidationRules
+export declare function allSchemas(config?: SeoFieldsPluginConfig): SchemaTypeDefinition[]
 
 export declare interface FieldVisibilityConfig {
-  hiddenFields?: AllFieldKeys[]
-  postType?: string
-}
-
-export declare const isMetaAttribute: (obj: any) => obj is MetaAttribute
-
-export declare const isOpenGraphSettings: (obj: any) => obj is OpenGraphSettings
-
-export declare const isSeoFields: (obj: any) => obj is SeoFields
-
-export declare const isTwitterCardSettings: (obj: any) => obj is TwitterCardSettings
-
-export declare interface MetaAttribute {
-  _type: 'metaAttribute'
-  key: string
-  type: 'string' | 'image'
-  value?: string
-  image?: SanityImage
+  hiddenFields?: ValidHiddenFieldKeys[]
 }
 
 export declare const metaAttributeSchema: {
@@ -90,11 +22,7 @@ export declare const metaAttributeSchema: {
             attributeValueString: string
             attributeValueImage: string
           },
-          {
-            attributeName: string
-            attributeValueString: string
-            attributeValueImage: any
-          }
+          Record<'attributeName' | 'attributeValueString' | 'attributeValueImage', any>
         >
       | undefined
   }
@@ -116,23 +44,7 @@ export declare type openGraphFieldKeys =
   | 'openGraphImage'
   | 'openGraphImageUrl'
 
-export declare function openGraphSchema(config?: SeoFieldsPluginConfig): {
-  type: 'object'
-  name: 'openGraph'
-} & Omit<ObjectDefinition, 'preview'> & {
-    preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
-  }
-
-export declare interface OpenGraphSettings {
-  _type: 'openGraph'
-  title?: string
-  description?: string
-  siteName?: string
-  type?: 'website' | 'article' | 'profile' | 'book' | 'music' | 'video' | 'product'
-  imageType?: 'upload' | 'url'
-  image?: SanityImageWithAlt
-  imageUrl?: string
-}
+export declare function openGraphSchema(config?: SeoFieldsPluginConfig): SchemaTypeDefinition
 
 export declare const robotsSchema: {
   type: 'object'
@@ -141,36 +53,6 @@ export declare const robotsSchema: {
     preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
   }
 
-export declare interface RobotsSettings {
-  noIndex?: boolean
-  noFollow?: boolean
-}
-
-export declare interface SanityImage {
-  _type: 'image'
-  asset: {
-    _ref: string
-    _type: 'reference'
-  }
-  hotspot?: {
-    x: number
-    y: number
-    height: number
-    width: number
-  }
-  crop?: {
-    top: number
-    bottom: number
-    left: number
-    right: number
-  }
-  alt?: string
-}
-
-export declare interface SanityImageWithAlt extends SanityImage {
-  alt: string
-}
-
 export declare interface SeoFieldConfig {
   title?: string
   description?: string
@@ -185,19 +67,6 @@ export declare type SeoFieldKeys =
   | 'metaAttributes'
   | 'robots'
 
-export declare interface SeoFields {
-  _type: 'seoFields'
-  robots?: RobotsSettings
-  preview?: string
-  title?: string
-  description?: string
-  metaImage?: SanityImage
-  keywords?: string[]
-  canonicalUrl?: string
-  openGraph?: OpenGraphSettings
-  twitter?: TwitterCardSettings
-}
-
 declare const seofields: Plugin_2<void | SeoFieldsPluginConfig>
 export default seofields
 
@@ -228,21 +97,17 @@ export declare interface SeoFieldsPluginConfig {
    * This allows customization of field titles and descriptions.
    * For example, to change the title of the 'title' field:
    */
-  fieldOverrides?: {
-    [key in AllFieldKeys]?: SeoFieldConfig
-  }
+  fieldOverrides?: Partial<Record<AllFieldKeys, SeoFieldConfig>>
   /**
    * A mapping of document types to field visibility configurations.
    * This allows you to specify which fields should be hidden for specific document types.
    */
-  fieldVisibility?: {
-    [postType: string]: FieldVisibilityConfig
-  }
+  fieldVisibility?: Record<string, FieldVisibilityConfig>
   /**
    * A list of fields that should be hidden by default in all document types.
    * This can be overridden by specific document type settings in `fieldVisibility`.
    */
-  defaultHiddenFields?: AllFieldKeys[]
+  defaultHiddenFields?: ValidHiddenFieldKeys[]
   /**
    * The base URL of your website, used for generating full URLs in the SEO preview.
    * Defaults to 'https://www.example.com' if not provided.
@@ -250,46 +115,7 @@ export declare interface SeoFieldsPluginConfig {
   baseUrl?: string
 }
 
-export declare function seoFieldsSchema(config?: SeoFieldsPluginConfig): {
-  type: 'object'
-  name: 'seoFields'
-} & Omit<ObjectDefinition, 'preview'> & {
-    preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
-  }
-
-export declare interface SeoValidationRules {
-  title: {
-    maxLength: number
-    warningLength: number
-  }
-  description: {
-    maxLength: number
-    warningLength: number
-  }
-  openGraphTitle: {
-    maxLength: number
-  }
-  openGraphDescription: {
-    maxLength: number
-  }
-  twitterTitle: {
-    maxLength: number
-  }
-  twitterDescription: {
-    maxLength: number
-  }
-}
-
-export declare interface TwitterCardSettings {
-  _type: 'twitter'
-  card?: 'summary' | 'summary_large_image' | 'app' | 'player'
-  site?: string
-  title?: string
-  description?: string
-  imageType?: 'upload' | 'url'
-  image?: SanityImageWithAlt
-  imageUrl?: string
-}
+export declare function seoFieldsSchema(config?: SeoFieldsPluginConfig): SchemaTypeDefinition
 
 export declare type twitterFieldKeys =
   | 'twitterCard'
@@ -301,11 +127,11 @@ export declare type twitterFieldKeys =
   | 'twitterImage'
   | 'twitterImageUrl'
 
-export declare function twitterSchema(config?: SeoFieldsPluginConfig): {
-  type: 'object'
-  name: 'twitter'
-} & Omit<ObjectDefinition, 'preview'> & {
-    preview?: PreviewConfig<Record<string, string>, Record<never, any>> | undefined
-  }
+export declare function twitterSchema(config?: SeoFieldsPluginConfig): SchemaTypeDefinition
+
+export declare type ValidHiddenFieldKeys = Exclude<
+  AllFieldKeys,
+  'openGraphImageUrl' | 'twitterImageUrl' | 'openGraphImageType' | 'twitterImageType'
+>
 
 export {}