Skip to main content

​
1. Overview

Sanity connector publishes Skayle posts as Sanity documents. It requires:
  • projectId
  • dataset
  • token
  • documentType
  • fieldMapping
  • taxonomyMapping

​
2. Prerequisites

Before connecting:
  • A Sanity project and dataset
  • A post-like document type in your schema
  • Category/tag/author taxonomy document types
  • API token with write access

​
3. Creating API credentials

In Sanity Studio/Manage:
  1. Go to Manage -> API -> Tokens.
  2. Create a token for Skayle.
  3. Copy the token value.
In Skayle connector settings, enter:
  • Project ID
  • Dataset
  • Token

​
4. Required permissions

Token must allow read and write operations. In practice, use a token with Editor or Administrator level capabilities so create/update operations succeed.

​
5. CMS-side setup

Create/confirm these schema elements:
  • Main post document type (for example post)
  • Fields for title, slug, excerpt, content
  • Optional fields for featured image, publish date, status
  • Taxonomy document types for category/tag/author
  • Reference fields on post documents for taxonomy relations
Notes:
  • Document type discovery in Skayle depends on available content and schema visibility.
  • If no content documents exist yet, you may need to create one to simplify type discovery.
No webhook setup is required.

​
6. Connecting in Skayle

  1. Open Settings -> Connector.
  2. Select Sanity.
  3. Enter project credentials and test connection.
  4. Choose your post documentType.
  5. Map Skayle fields to Sanity fields.
  6. Map taxonomy types (category, tag, author).
  7. Save connector.

​
7. Field mapping explanation

Sanity mapping is explicit. Required post field mappings:
  • Title
  • Slug
  • Excerpt
  • Content
Optional mappings:
  • Featured image
  • Publish date
  • Status
  • Taxonomy reference fields (category/tags/author)
Taxonomy mapping maps each Skayle taxonomy type to a Sanity document type.

​
8. Publishing test article

  1. Create a draft in Skayle.
  2. Assign category/tag/author.
  3. Publish from Skayle.
  4. Confirm document appears in selected Sanity document type.
  5. Verify taxonomy references and mapped fields.

​
9. Common errors & troubleshooting

IssueLikely causeFix
Connection test failsInvalid project/dataset/tokenRe-check all three values
Permission/write errorsToken lacks create/update rightsRegenerate token with Editor/Admin privileges
Missing fields in mapping stepSchema type not discoverableConfirm schema exists and create sample docs if needed
Taxonomy references emptyTaxonomy mapping not configured or unsyncedComplete taxonomy mapping and sync taxonomies
Slug/content not updatingIncorrect field mappingVerify exact field names in Sanity schema

​
10. Best practices

  • Keep one canonical post document type for Skayle publishing.
  • Keep taxonomy document types stable once mapped.
  • Validate mapping on one test post before bulk publishing.
  • Use clear naming for schema fields to reduce mapping mistakes.