Sanity.io Integration

iContentForge seamlessly integrates with Sanity.io, allowing you to automatically publish AI-generated articles directly to your Sanity dataset. This guide walks you through the connection setup and field mapping process.

Prerequisites

Before you begin, ensure you have:

• An active iContentForge project with generated articles.
• A Sanity.io project with a dataset (typically production).
• Admin or Editor permissions in your Sanity project to generate API tokens.

Generating Sanity API Credentials

iContentForge requires a Write Token to publish content to your Sanity dataset. Follow these steps to generate one:

1. Log in to your Sanity.io Manage dashboard.
2. Select your project from the list.
3. Navigate to Settings > API.
4. In the "Tokens" section, click Add API token.
5. Configure the new token:
   • Name: e.g., iContentForge Publish Token
   • Role: Select Editor (requires write permissions).
   • Permissions: Ensure create, update, and publish are enabled.
6. Click Generate. Copy the token immediately, as it will not be shown again.

Recommended: The Official Zero-Config Template

If your Sanity schema is highly customized or you are experiencing mapping errors, we strongly recommend using our standard schema. This bypasses all manual field mapping and guarantees 100% compatibility with iContentForge's automated publishing.

1. Download sanity-icontentforge-schema.ts
2. Place this file inside your Sanity project's schemas/ folder.
3. Add icf_post to your document types list in schemas/index.ts (or schema.ts).
4. Run sanity deploy.
5. In iContentForge, just set Document Type to icf_post and all fields will automatically map!

Connecting iContentForge to Sanity

With your credentials ready, establish the connection:

1. In your iContentForge dashboard, go to your Project and open the CMS Integrations tab.
2. Click Add New Integration and select Sanity.io from the list.
3. Fill in the connection details:
   • Project ID: Found in your Sanity project's sanity.json file or on the API settings page (e.g., abc123def).
   • Dataset: The name of the dataset to publish to (e.g., production).
   • Write Token: The API token you generated in the previous step.
   • Document Type (Schema): The _type name of your Sanity document schema for articles (e.g., post, article, blogPost). Check your Sanity Studio schema files if unsure.
   • Author Name (Optional): A display name for the author field in published documents.
   • Field Type Overrides (Optional JSON): A schema hint object such as {"body":"portable_text","slug":"slug","tags":"array<string>"}. This enables pre-publish validation so iContentForge can catch type mismatches before the mutation reaches Sanity.

4. Click Test Connection. A success message confirms your credentials are valid.
5. Click Save & Configure to proceed to field mapping.

Schema-Aware Validation

Sanity is a schema-driven CMS, which means two websites can both use a field named body while expecting completely different value shapes. One site may want Portable Text, another may store plain strings, and another may rely on custom objects.

To reduce failed publishes and broken front-end rendering, iContentForge supports Field Type Overrides in the connector settings. This lets you tell the publisher what your Sanity schema expects for the fields you mapped.

Why this matters

Without schema-aware validation:

• A publish can fail at mutation time because the value shape is wrong.
• A publish can succeed, but render incorrectly in your front-end because the stored value type does not match what your components expect.
• Debugging gets slower because the error only appears after content has already been pushed to Sanity.

With schema-aware validation:

• slug fields are validated and wrapped as { _type: "slug", current: "..." }
• portable_text fields are checked before publish
• datetime fields are normalized as ISO timestamps
• array<string> fields are validated before mutation
• Invalid combinations are rejected early with a descriptive error

Supported Sanity type hints

Use the optional JSON field in the connector UI to override types for mapped fields:

{
  "title": "string",
  "slug": "slug",
  "body": "portable_text",
  "excerpt": "text",
  "metaTitle": "string",
  "metaDescription": "text",
  "categories": "array<string>",
  "tags": "array<string>",
  "publishedAt": "datetime"
}

This is especially useful when your schema differs from the default assumptions used by iContentForge.

GROQ Schema Field Mapping

After connecting, you must map iContentForge's article data to the fields in your Sanity document schema. This tells iContentForge where to place the title, body, slug, etc.

1. In the configuration panel, you will see a list of iContentForge Fields (Source) and empty dropdowns for Sanity Fields (Target).
2. For each source field, select the corresponding target field from your Sanity schema.
   • The dropdown is populated by fetching your Sanity schema's document type(s).

Default Field Mapping

Here is the standard mapping for a typical blog post schema (post or article):

3. Select the Target Document Type: Choose the Sanity document type (e.g., post, article) you want to publish to from the dropdown.
4. (Optional) Configure Default Values for any fields in your schema that are required but not mapped (e.g., set a default status to published).
5. Click Save Mapping.

Publishing and Workflow

Once configured, your integration is active.

• Articles in iContentForge with a status of Ready can be published individually or in bulk.
• If Drip Feed is enabled for your project, articles will be automatically published to Sanity according to your schedule (approximately every 5 minutes).
• iContentForge uses the createOrReplace mutation if a document with the same slug already exists, it will be updated rather than duplicated.
• Published articles will appear in your Sanity studio with the status Published.
• The article status in iContentForge will update from Ready to Published upon successful sync.

To troubleshoot failed publishes, check the article status log in iContentForge for error details. Common issues include schema validation errors (e.g., a required field in your Sanity schema is not mapped) or mismatched document type names.

Troubleshooting

Next Steps

• Learn how to automate publishing with Drip Feed Scheduling.
• Understand the different Article Statuses in the publishing pipeline.
• Explore other available CMS Integrations.