Skip to main content

​
Overview

The Sanity connector integrates with Sanity’s structured content platform, converting Skayle articles to Portable Text format. It supports:
  • Publishing to any Sanity document type
  • Flexible field mapping for custom schemas
  • Category, tag, and author synchronization via references
  • Asset management for images
  • Scheduled publishing

​
Prerequisites

Before connecting, ensure you have:
  1. Sanity project with a dataset
  2. API token with write permissions
  3. Document type for blog posts/articles
  4. Reference types for categories, tags, and authors (optional)

​
Setup Guide

​
Step 1: Get Your Project Credentials

  1. Go to sanity.io/manage
  2. Select your project
  3. Note your Project ID (e.g., abc123xyz)
  4. Note your Dataset name (usually production)

​
Step 2: Create an API Token

  1. In your Sanity project, go to API → Tokens
  2. Click Add API token
  3. Name it (e.g., “Skayle Integration”)
  4. Select Editor permissions (or custom with write access)
  5. Click Save and copy the token
Store your API token securely. It provides write access to your Sanity dataset.

​
Step 3: Configure Field Mapping

Skayle needs to know how your Sanity schema maps to article fields: 
interface SanityConnectorConfig {
  type: "sanity";
  projectId: string;      // Your Sanity project ID
  dataset: string;        // Dataset name (e.g., "production")
  token: string;          // API token with write access
  documentType: string;   // Document type for articles (e.g., "post")
  useCdn?: boolean;       // Use CDN for reads (default: false)

  fieldMapping: {
    title: string;        // Field name for title
    slug: string;         // Field name for slug
    excerpt: string;      // Field name for excerpt
    content: string;      // Field name for body/content
    featuredImage?: string; // Field name for main image
    publishAt?: string;   // Field name for publish date
    status?: string;      // Field name for status
  };

  taxonomyMapping: {
    category: string;     // Reference field for categories
    tag: string;          // Reference field for tags
    author: string;       // Reference field for author
  };
}

​
Step 4: Configure in Skayle

  1. Go to Settings → Connectors in Skayle
  2. Select Sanity as your connector type
  3. Enter your configuration:
FieldDescriptionExample
Project IDYour Sanity project IDabc123xyz
DatasetDataset nameproduction
TokenAPI tokensk...
Document TypeSchema type for postspost
Title FieldField name for titletitle
Slug FieldField name for slugslug.current
Content FieldField name for bodybody
Excerpt FieldField name for excerptexcerpt
  1. Click Test Connection to verify

​
Example Sanity Schema

Here’s a recommended schema for blog posts that works well with Skayle: 
// schemas/post.js
export default {
  name: "post",
  title: "Post",
  type: "document",
  fields: [
    {
      name: "title",
      title: "Title",
      type: "string",
      validation: (Rule) => Rule.required(),
    },
    {
      name: "slug",
      title: "Slug",
      type: "slug",
      options: { source: "title", maxLength: 96 },
      validation: (Rule) => Rule.required(),
    },
    {
      name: "excerpt",
      title: "Excerpt",
      type: "text",
      rows: 3,
    },
    {
      name: "mainImage",
      title: "Main Image",
      type: "image",
      options: { hotspot: true },
    },
    {
      name: "body",
      title: "Body",
      type: "blockContent", // Portable Text
    },
    {
      name: "categories",
      title: "Categories",
      type: "array",
      of: [{ type: "reference", to: { type: "category" } }],
    },
    {
      name: "tags",
      title: "Tags",
      type: "array",
      of: [{ type: "reference", to: { type: "tag" } }],
    },
    {
      name: "author",
      title: "Author",
      type: "reference",
      to: { type: "author" },
    },
    {
      name: "publishedAt",
      title: "Published at",
      type: "datetime",
    },
  ],
};

​
Content Formatting

Skayle converts BlockNote JSON to Sanity Portable Text format:

​
Portable Text Structure

[
  {
    _key: "abc123",
    _type: "block",
    style: "normal",
    children: [{ _key: "def456", _type: "span", text: "Hello world" }],
  },
  {
    _key: "ghi789",
    _type: "block",
    style: "h2",
    children: [{ _key: "jkl012", _type: "span", text: "Section Title" }],
  },
];

​
Supported Block Types

BlockNote TypePortable Text Style
Paragraphnormal
Heading 1h1
Heading 2h2
Heading 3h3
Heading 4h4
Heading 5h5
Heading 6h6
Bullet Listbullet
Numbered Listnumber
Blockquoteblockquote
Codenormal with code mark

​
Marks (Inline Formatting)

FormatPortable Text Mark
Boldstrong
Italicem
Underlineunderline
Strikethroughstrike-through
Codecode
Linklink with href

​
Taxonomy Mapping

​
References

Sanity uses references for relationships. When publishing:
  1. Skayle looks up the category/tag/author in the mapping table
  2. Creates a Sanity reference: { _type: "reference", _ref: "sanity-doc-id" }
  3. Assigns references to the appropriate fields

​
Syncing Taxonomies

Fetches documents of your taxonomy types and creates Skayle equivalents:
*[_type == "category"] { _id, name, slug }
*[_type == "tag"] { _id, name, slug }
*[_type == "author"] { _id, name, slug }

​
Image Handling

The connector handles images in two ways:

​
External URLs

If your schema accepts URL strings, images are passed as URLs: 
{
  mainImage: "https://example.com/image.jpg"
}

​
Sanity Assets

For proper Sanity image assets, the connector can upload images: 
{
  mainImage: {
    _type: "image",
    asset: {
      _type: "reference",
      _ref: "image-abc123-1200x800-jpg"
    }
  }
}
Asset upload requires additional API calls and may increase publishing time.

​
Troubleshooting

​
Connection Issues

  • Verify your API token is correct
  • Check token hasn’t expired
  • Ensure token has write permissions
  • Verify Project ID is correct
  • Check dataset name matches exactly
  • Ensure project is active
  • Verify field mapping matches your schema
  • Check required fields are mapped
  • Ensure field types are compatible

​
Publishing Issues

  • Check Sanity Studio for draft documents
  • Verify document type exists in schema
  • Check for validation errors in Sanity
  • Ensure taxonomy documents exist in Sanity
  • Run taxonomy sync first
  • Verify reference field types match
  • Verify your frontend handles Portable Text
  • Check block types are supported
  • Use @portabletext/react for rendering

​
Best Practices

  1. Use consistent schemas: Keep your Sanity schema aligned with Skayle’s field mapping
  2. Sync taxonomies first: Always sync taxonomies before publishing articles
  3. Test with drafts: Use Sanity’s draft system to preview before publishing
  4. Monitor mutations: Use Sanity’s history to track changes from Skayle
  5. Backup regularly: Export your dataset periodically

​
Next Steps

Content Formatting

Learn about content conversion for different CMS platforms

Scheduled Publishing

Set up automated content publishing