> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skayle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sanity Setup

> Connect Sanity with project credentials, map document fields, and sync taxonomy document types.

## 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

| Issue                          | Likely cause                                | Fix                                                    |
| ------------------------------ | ------------------------------------------- | ------------------------------------------------------ |
| Connection test fails          | Invalid project/dataset/token               | Re-check all three values                              |
| Permission/write errors        | Token lacks create/update rights            | Regenerate token with Editor/Admin privileges          |
| Missing fields in mapping step | Schema type not discoverable                | Confirm schema exists and create sample docs if needed |
| Taxonomy references empty      | Taxonomy mapping not configured or unsynced | Complete taxonomy mapping and sync taxonomies          |
| Slug/content not updating      | Incorrect field mapping                     | Verify 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.