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

# Sanity setup

> Connect a Sanity project and dataset, review the document fields, and verify a test draft before sending articles.

The Sanity connection sends articles to one document type in your dataset. Weelkit reads your deployed Studio schema and asks you to review the field mapping before publishing.

## Connect a dataset

**1. Choose Sanity**

In **Organization settings → CMS**, choose **Connect CMS**, then **Sanity**.

**2. Enter the connection details**

Enter your **Project ID** and **Dataset**. You can find the project ID in your Sanity project settings or Studio configuration.

**Workspace** is optional. Enter the Studio workspace name when the dataset has multiple deployed schemas.

Enter an **API token** with read and write access to the dataset, then choose **Connect**.

**3. Choose a document type**

After the connection is saved, choose **Next**. Select the one Sanity document type Weelkit should use for articles, then choose **Next** to read its fields.

If Weelkit says your Sanity schema isn't deployed, see [Deploy your schema](#deploy-your-schema).

**4. Save the field mapping**

Review the suggested mappings and choose the Sanity fields for your article values. Choose **Save mapping** to save changes, or **Next** if shown. Only the saved mapping decides what Weelkit sends.

**5. Choose publishing defaults**

Set **Default status** to **Draft** or **Published**, when publishing is available for the selected type. Choose what happens **When the article already exists**: **Ask before updating**, **Always update existing**, or **Always create a new item**. Choose **Save and continue**.

**6. Verify a test draft**

Choose **Verify test draft**. Weelkit uses your saved mapping to create a temporary draft and read it back. Review the field results and inspect the draft in Sanity. You can choose **Delete draft** to remove it.

When verification succeeds, choose **Continue** to finish setup.

## Deploy your schema

Weelkit reads your fields from the schema deployed to your dataset, which Sanity stores there as `system.schema` documents. It does not read your Studio files. When no schema is deployed, setup stops and asks you to contact your Sanity developer. They deploy it with one command in your Studio project.

For a Sanity-hosted Studio, deploying the Studio also deploys the schema:

```bash theme={null}
npx sanity deploy
```

For a self-hosted or embedded Studio, deploy the schema directly:

```bash theme={null}
npx sanity schemas deploy
```

To register a Studio that you host yourself, `npx sanity deploy --external --url <studio-url>` also deploys the schema.

Sanity Studio v3.88 or later is required. Deploy again whenever the schema changes, so Weelkit sees the new fields.

When the deploy finishes, return to Weelkit and choose **Check again**.

## Preserve content your schema cannot express

Weelkit first uses the native Portable Text members your schema declares. When a native member cannot keep a block's full content, a declared object with a writable `html` string/text field can preserve its canonical HTML. For example, the selected body field can include:

```javascript theme={null}
{
  name: 'body',
  type: 'array',
  of: [
    {type: 'block'},
    {
      name: 'htmlBlock',
      type: 'object',
      fields: [{name: 'html', type: 'text'}]
    }
  ]
}
```

The object's `html` field must accept the whole fragment. Limits, options or validation that prevent this are incompatible, as are other required fields Weelkit cannot fill. Content outside the canonical article vocabulary is still rejected.

Your website must register a Portable Text component for the exact `htmlBlock` type and render its HTML safely without dropping supported markup. Adding the Studio schema alone does not make it appear on your website. See Sanity's [Add custom blocks](https://www.sanity.io/docs/studio/portable-text-editor-configuration) and [Rendering Portable Text in React](https://www.sanity.io/docs/developer-guides/presenting-block-text) sections.

Deploy the schema before setup. For an existing connection, open **Destination → Refresh destination fields**, review **Field mapping**, save it and choose **Verify test draft** again. Inspect both Studio and the rendered test page. Without a compatible native member or HTML object, Weelkit explains the unsupported block before sending anything.

A document's creation or update timestamp is not its publication date. A missing publication date shows **—**.

## Dates and value lists

Use a calendar date such as `2025-02-03` for a mapped `date`, and an ISO date and time such as `2025-02-03T04:05:06Z` for `datetime`. Your authored value is not replaced with the time of the send. See Sanity's [Date type](https://www.sanity.io/docs/studio/date-type) and [Datetime type](https://www.sanity.io/docs/studio/datetime-type) definitions and validation sections.

**Value list** supports declared text, number, integer and boolean members, including declared combinations of those types. Each member keeps its type, order and constraints. Lists of dates, datetimes or URLs are not qualified. Sanity also forbids mixing objects and primitive values in one list; see [Array — Limitations](https://www.sanity.io/docs/studio/array-type).

## Send an article

Open the article in the editor and choose **Send draft to CMS** or **Publish to CMS**, according to your saved default. See [Send to your CMS](https://docs.weelkit.com/articles/checks-and-publishing.md#send-to-your-cms) for updates and confirmation.

## Finish setup later

Choose **Finish later** to leave setup. The saved connection remains in **Organization settings → CMS**. Choose **Continue setup** on the connection when you are ready to resume.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.