# Changelog
Source: https://docs.contentwrap.io/changelog

Track ContentWrap's latest features, improvements, and bug fixes

## Overview

Stay up to date with the latest ContentWrap releases, new features, and improvements. We're continuously working to make your Webflow to Sanity migrations faster, easier, and more reliable.

<Note>
  ContentWrap is currently in beta. We're actively developing new features and refining the migration experience based on user feedback.
</Note>

## Latest Updates

### Coming Soon

We're working on several exciting features:

* **Reference Resolution**: Automatic handling of Webflow reference fields
* **Multi-Collection Import**: Migrate multiple collections in a single workflow
* **Schema Generation**: Auto-generate Sanity schema files from your mappings
* **Saved Mappings**: Reuse field mappings for recurring migrations

<Tip>
  Want to be notified about new releases? Follow us on [X/Twitter](https://x.com/contentwrap) or check back here regularly.
</Tip>

## How to Report Issues

Found a bug or have a feature request?

* **Email**: [support@contentwrap.io](mailto:support@contentwrap.io)
* **Include**: Error messages, steps to reproduce, and your use case

***

*This changelog will be updated as we ship new features and improvements.*


# How Field Mapping Works
Source: https://docs.contentwrap.io/concepts/field-mapping

Understand MigrateKit's field mapping system and how it transforms Webflow CSV data into structured Sanity documents.

## What is Field Mapping?

Field mapping defines the relationship between your Webflow CSV columns and Sanity document fields. It tells MigrateKit:

1. **What** each column represents (title, body, image, etc.)
2. **How** to transform the data (HTML → Portable Text, URL → image)
3. **Where** to put it in your Sanity schema (field names)

\##The Mapping Process

<Steps>
  <Step title="Analyze CSV Structure">
    MigrateKit reads your CSV headers and sample data to understand what you have
  </Step>

  <Step title="Suggest Mappings">
    Based on column names and data types, MigrateKit suggests appropriate Sanity field types
  </Step>

  <Step title="You Review & Adjust">
    Accept suggestions or manually configure mappings for each field
  </Step>

  <Step title="Validate">
    MigrateKit checks that all mappings are valid before allowing import
  </Step>
</Steps>

## Auto-Mapping Intelligence

MigrateKit uses pattern matching to suggest mappings:

### Name-Based Matching

| Webflow Column                    | Detected As      | Suggested Type |
| --------------------------------- | ---------------- | -------------- |
| Name, Title, Heading              | Title field      | `string`       |
| Slug, URL Slug                    | URL identifier   | `slug`         |
| Post Body, Content, Rich Text     | Rich content     | `portableText` |
| Main Image, Hero Image, Thumbnail | Primary image    | `image`        |
| Published Date, Date Published    | Publication date | `datetime`     |
| Featured, Active, Published       | Toggle field     | `boolean`      |

### Data-Based Detection

MigrateKit also inspects sample values:

* **ISO dates** (`2024-01-15T10:30:00.000Z`) → `datetime`
* **URLs** (`https://...`) → `url` or `image`
* **Numbers** (`100`, `3.14`) → `number`
* **True/false** (`true`, `false`, `yes`, `no`) → `boolean`
* **HTML tags** (`<p>`, `<h2>`) → `portableText`

## Transformation Pipeline

When you map a field, MigrateKit applies transformations during import:

```mermaid theme={null}
graph LR
    A[CSV Value] --> B{Field Type}
    B -->|string| C[Clean Text]
    B -->|portableText| D[HTML → PT]
    B -->|image| E[Download & Upload]
    B -->|slug| F[Sanitize]
    B -->|datetime| G[Parse Date]
    C --> H[Sanity Document]
    D --> H
    E --> H
    F --> H
    G --> H
```

### String Fields

* Trim whitespace
* Remove null bytes
* Preserve Unicode

### Portable Text

1. Parse HTML structure
2. Map tags to blocks
3. Extract inline formatting
4. Create Portable Text JSON

Learn more: [HTML Conversion](/concepts/html-conversion)

### Image Fields

1. Validate URL format
2. Download from source
3. Check for duplicates
4. Upload to Sanity
5. Create asset reference

### Slug Fields

1. Lowercase value
2. Remove special characters
3. Replace spaces with hyphens
4. Create slug object: `{current: "value"}`

### Date/Time Fields

1. Parse various formats:
   * ISO 8601: `2024-01-15T10:30:00.000Z`
   * Simple date: `2024-01-15`
   * US format: `01/15/2024` (if unambiguous)
2. Convert to ISO format
3. Validate range (1900-2100)

### Number Fields

1. Parse as float or integer
2. Handle separators (`,` `1,000` → `1000`)
3. Validate numeric
4. Preserve decimal precision

### Boolean Fields

Convert various representations:

| CSV Value                 | Boolean |
| ------------------------- | ------- |
| `true`, `True`, `TRUE`    | `true`  |
| `false`, `False`, `FALSE` | `false` |
| `yes`, `Yes`, `YES`, `1`  | `true`  |
| `no`, `No`, `NO`, `0`     | `false` |

## Validation Rules

MigrateKit validates mappings before import:

### Schema Validation

* **Document type** - Valid Sanity identifier (no spaces, special chars)
* **Field names** - Unique, valid identifiers
* **Required fields** - Must have mappings

### Data Validation

* **Type compatibility** - CSV values can convert to target type
* **Required data** - Required fields have values in CSV
* **Format validity** - Dates parse, URLs are valid, etc.

### Preview Validation

Sample documents show you exactly what will be imported:

## Common Mapping Patterns

### Basic Blog Post

| Webflow Column | Sanity Field | Type           |
| -------------- | ------------ | -------------- |
| Name           | title        | `string`       |
| Slug           | slug         | `slug`         |
| Post Body      | content      | `portableText` |
| Main Image     | coverImage   | `image`        |
| Published Date | publishedAt  | `datetime`     |
| Featured       | featured     | `boolean`      |

### E-commerce Product

| Webflow Column | Sanity Field | Type               |
| -------------- | ------------ | ------------------ |
| Name           | title        | `string`           |
| Slug           | slug         | `slug`             |
| Description    | description  | `portableText`     |
| Price          | price        | `number`           |
| Product Image  | images       | `array` of `image` |
| In Stock       | inStock      | `boolean`          |

### Author/Person

| Webflow Column | Sanity Field | Type           |
| -------------- | ------------ | -------------- |
| Name           | name         | `string`       |
| Slug           | slug         | `slug`         |
| Bio            | bio          | `portableText` |
| Photo          | photo        | `image`        |
| Email          | email        | `string`       |
| Twitter Handle | twitter      | `string`       |

## Advanced Mapping

### Arrays

Map comma-separated values to arrays:

**CSV:**

```csv theme={null}
Tags
"webflow,sanity,migration"
```

**Mapping:**

* Field type: `array`
* Item type: `string`

**Result:**

```json theme={null}
{
  "tags": ["webflow", "sanity", "migration"]
}
```

### Nested Objects

While MigrateKit doesn't support complex nested mappings in MVP, you can:

1. Import flat data
2. Manually restructure in Sanity Studio
3. Or use Sanity's GROQ projections after import

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive field names">
    Choose names that clearly indicate content:

    * ✅ `coverImage`, `heroImage`
    * ❌ `img`, `pic1`, `image-main`

    Good names make your Sanity schema self-documenting.
  </Accordion>

  <Accordion title="Follow Sanity conventions">
    Use camelCase for field names:

    * ✅ `publishedAt`, `authorName`
    * ❌ `published_at`, `author-name`

    This matches Sanity's standard patterns.
  </Accordion>

  <Accordion title="Map selectively">
    You don't have to map every column:

    * Skip Webflow system fields (`Collection ID`, `Item ID`)
    * Skip deprecated or unused fields
    * Skip fields you'll add manually later

    Less clutter = easier schema maintenance.
  </Accordion>

  <Accordion title="Plan for references">
    If columns reference other collections:

    1. Note the relationship
    2. Map as `string` for now (stores the ID/slug)
    3. Manually recreate references in Sanity after import

    Future: MigrateKit will support automatic reference resolution.
  </Accordion>

  <Accordion title="Test with preview">
    Always review sample documents before importing:

    * Check Portable Text renders correctly
    * Verify dates parse properly
    * Confirm images reference correctly
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Field type mismatch' error">
    **Cause:** Data in column doesn't match selected field type.

    **Example:** Mapping text column to `number` field.

    **Fix:**

    * Choose correct field type for the data
    * OR clean data in CSV before upload
  </Accordion>

  <Accordion title="'Required field has empty values'">
    **Cause:** Some rows are missing data for a required field.

    **Fix:**

    * Make field optional (uncheck "Required")
    * OR fill missing values in CSV
    * OR accept that rows with missing data will fail
  </Accordion>

  <Accordion title="Auto-mapping got it wrong">
    **Cause:** Column name or data pattern was ambiguous.

    **Fix:** Manually adjust the mapping—auto-suggestions are just starting points.
  </Accordion>

  <Accordion title="Can't map reference fields">
    **Current limitation:** Reference fields aren't supported in MVP.

    **Workaround:**

    * Map as `string` to preserve the ID/slug
    * Manually link references in Sanity Studio after import
  </Accordion>
</AccordionGroup>


# HTML to Portable Text Conversion
Source: https://docs.contentwrap.io/concepts/html-conversion

Understand how MigrateKit intelligently converts Webflow's HTML rich text to Sanity's Portable Text format with semantic preservation.

## How Conversion Works

MigrateKit automatically converts HTML from Webflow's rich text fields into Sanity's Portable Text format during migration. This process:

1. **Parses HTML** - Reads your Webflow HTML structure
2. **Maps tags to blocks** - Converts HTML tags to Portable Text blocks and marks
3. **Preserves semantics** - Maintains meaning, not just visual appearance
4. **Handles edge cases** - Wraps unsupported content as code blocks

## Supported HTML Tags

MigrateKit handles most common HTML tags from Webflow:

### Headings

| HTML   | Portable Text | Usage               |
| ------ | ------------- | ------------------- |
| `<h1>` | `style: "h1"` | Top-level headings  |
| `<h2>` | `style: "h2"` | Section headings    |
| `<h3>` | `style: "h3"` | Subsection headings |
| `<h4>` | `style: "h4"` | Minor headings      |
| `<h5>` | `style: "h5"` | Rarely used         |
| `<h6>` | `style: "h6"` | Rarely used         |

### Paragraphs & Line Breaks

* `<p>` → `style: "normal"` block
* `<br>` → New line within block
* Multiple `<br>` → New blocks

### Text Formatting

| HTML           | Portable Text Mark          | Visual            |
| -------------- | --------------------------- | ----------------- |
| `<strong>`     | `marks: ["strong"]`         | **Bold**          |
| `<b>`          | `marks: ["strong"]`         | **Bold**          |
| `<em>`         | `marks: ["em"]`             | *Italic*          |
| `<i>`          | `marks: ["em"]`             | *Italic*          |
| `<u>`          | `marks: ["underline"]`      | Underlined        |
| `<s>`, `<del>` | `marks: ["strike-through"]` | ~~Strikethrough~~ |
| `<code>`       | `marks: ["code"]`           | `Inline code`     |

### Lists

**Unordered lists:**

```html theme={null}
<ul>
  <li>First item</li>
  <li>Second item</li>
</ul>
```

Becomes:

```json theme={null}
[
  {"_type": "block", "listItem": "bullet", "children": [...]},
  {"_type": "block", "listItem": "bullet", "children": [...]}
]
```

**Ordered lists:**

```html theme={null}
<ol>
  <li>First step</li>
  <li>Second step</li>
</ol>
```

Becomes:

```json theme={null}
[
  {"_type": "block", "listItem": "number", "children": [...]},
  {"_type": "block", "listItem": "number", "children": [...]}
]
```

**Nested lists** are supported with proper indentation levels.

### Links

```html theme={null}
<a href="https://example.com">Click here</a>
```

Becomes:

```json theme={null}
{
  "_type": "span",
  "text": "Click here",
  "marks": [{
    "_type": "link",
    "href": "https://example.com"
  }]
}
```

**Link attributes:**

* `href` - Preserved as `href`
* `target="_blank"` - Preserved as `blank: true`
* `rel` - Preserved if present

### Images (Inline)

Images within rich text are converted to image blocks:

```html theme={null}
<p>Here's an image: <img src="/image.jpg" alt="Description"></p>
```

Becomes separate blocks:

```json theme={null}
[
  {"_type": "block", "children": [{"text": "Here's an image:"}]},
  {"_type": "image", "asset": {...}, "alt": "Description"}
]
```

## Handled with Warnings

Some HTML requires special handling:

### Inline Styles

```html theme={null}
<span style="color: red;">Red text</span>
```

Inline `style` attributes are **stripped** during conversion. Portable Text doesn't preserve inline CSS.

**Why?** Portable Text separates content from presentation. You style content in your frontend, not in the CMS.

### Custom Classes

```html theme={null}
<div class="custom-webflow-class">Content</div>
```

Class names are **not preserved**. Portable Text has no concept of CSS classes.

**Solution:** Use custom Portable Text blocks in Sanity for special formatting needs.

## Unsupported Content → Code Blocks

Anything we can't map to a Portable Text block/mark is wrapped as a `code` block with `language: "html"`. Examples:

### Scripts & Embeds

```html theme={null}
<script>alert('hello');</script>
```

Becomes:

```json theme={null}
{
  "_type": "code",
  "language": "html",
  "code": "<script>alert('hello');</script>"
}
```

### Iframes

```html theme={null}
<iframe src="https://youtube.com/embed/abc123"></iframe>
```

Becomes:

```json theme={null}
{
  "_type": "code",
  "language": "html",
  "code": "<iframe src=\"https://youtube.com/embed/abc123\"></iframe>"
}
```

### Custom Webflow Elements & Unknown Tags

```html theme={null}
<custom-element data-foo="bar">Content</custom-element>
```

Becomes:

```json theme={null}
{
  "_type": "code",
  "language": "html",
  "code": "<custom-element data-foo=\"bar\">Content</custom-element>"
}
```

These appear as code in Sanity and won't execute. Replace with Sanity-native components (e.g., YouTube plugin or custom embed blocks) after import.

## Conversion Examples

<Tabs>
  <Tab title="Basic Formatting">
    **HTML:**

    ```html theme={null}
    <h2>My Blog Post</h2>
    <p>This is <strong>bold</strong> and <em>italic</em> text.</p>
    <p>Here's a <a href="/link">link</a>.</p>
    ```

    **Portable Text:**

    ```json theme={null}
    [
      {
        "_type": "block",
        "style": "h2",
        "children": [{"text": "My Blog Post"}]
      },
      {
        "_type": "block",
        "children": [
          {"text": "This is "},
          {"text": "bold", "marks": ["strong"]},
          {"text": " and "},
          {"text": "italic", "marks": ["em"]},
          {"text": " text."}
        ]
      },
      {
        "_type": "block",
        "children": [
          {"text": "Here's a "},
          {"text": "link", "marks": [{"_type": "link", "href": "/link"}]},
          {"text": "."}
        ]
      }
    ]
    ```
  </Tab>

  <Tab title="Lists">
    **HTML:**

    ```html theme={null}
    <ul>
      <li>First item</li>
      <li>Second item with <strong>bold</strong></li>
    </ul>
    ```

    **Portable Text:**

    ```json theme={null}
    [
      {
        "_type": "block",
        "listItem": "bullet",
        "children": [{"text": "First item"}]
      },
      {
        "_type": "block",
        "listItem": "bullet",
        "children": [
          {"text": "Second item with "},
          {"text": "bold", "marks": ["strong"]}
        ]
      }
    ]
    ```
  </Tab>

  <Tab title="Complex Nesting">
    **HTML:**

    ```html theme={null}
    <p>A paragraph with <a href="/link"><strong>bold link</strong></a>.</p>
    ```

    **Portable Text:**

    ```json theme={null}
    [
      {
        "_type": "block",
        "children": [
          {"text": "A paragraph with "},
          {
            "text": "bold link",
            "marks": ["strong", {"_type": "link", "href": "/link"}]
          },
          {"text": "."}
        ]
      }
    ]
    ```
  </Tab>
</Tabs>

## Best Practices

### Before Migration

<Steps>
  <Step title="Clean up Webflow content">
    Remove unnecessary HTML before exporting:

    * Delete empty `<div>` and `<span>` tags
    * Remove inline styles you don't need
    * Simplify complex nested structures
  </Step>

  <Step title="Identify custom elements">
    Note any Webflow-specific elements that will need replacement:

    * Custom interactions
    * Dynamic embeds
    * Complex grids or layouts
  </Step>

  <Step title="Test with small sample">
    Export a small collection first to see how your HTML converts
  </Step>
</Steps>

### After Migration

<Steps>
  <Step title="Review code blocks">
    Check all code blocks in Sanity Studio:

    * Replace scripts with Sanity-safe alternatives
    * Convert iframes to proper embeds
    * Remove unnecessary preserved HTML
  </Step>

  <Step title="Fix formatting issues">
    Adjust any conversion quirks:

    * Incorrect heading levels
    * Lost spacing
    * Misinterpreted formatting
  </Step>

  <Step title="Add semantic improvements">
    Enhance content with Portable Text features:

    * Custom block types
    * Better link handling
    * Responsive embeds
  </Step>
</Steps>

## Common Issues

<AccordionGroup>
  <Accordion title="Line breaks disappeared">
    **Cause:** Multiple `<br>` tags or `<p>` tags with empty content.

    **Fix:** Manually add paragraph breaks in Sanity Studio where needed.
  </Accordion>

  <Accordion title="Formatting looks different">
    **Cause:** Inline styles or classes were stripped during conversion.

    **Fix:** Portable Text separates content from styling. Style your content in your frontend rendering, not in the CMS.
  </Accordion>

  <Accordion title="Images are missing">
    **Cause:** Images didn't upload (network error, quota exceeded).

    **Fix:** Check the import report for asset failures and manually upload missing images.
  </Accordion>

  <Accordion title="Links are broken">
    **Cause:** Relative Webflow links may not work in new context.

    **Fix:** Update links in Sanity Studio to point to correct URLs.
  </Accordion>

  <Accordion title="Custom elements became code blocks">
    **Expected:** MigrateKit preserves unknown HTML as code blocks for safety.

    **Fix:** Review code blocks and replace with Sanity-compatible alternatives.
  </Accordion>
</AccordionGroup>


# Understanding Portable Text
Source: https://docs.contentwrap.io/concepts/portable-text

Learn about Sanity's Portable Text format and how MigrateKit converts HTML to structured, platform-agnostic content.

## What is Portable Text?

Portable Text is Sanity's rich text format—a structured, JSON-based way to represent content that's more powerful and flexible than HTML.

Unlike HTML (which mixes content and presentation), Portable Text separates **what** the content is from **how** it looks. This makes your content:

* **Platform-agnostic** - Render on web, mobile, email, or anywhere
* **Structured** - Query and filter content programmatically
* **Customizable** - Style differently across platforms
* **Future-proof** - Not tied to specific HTML/CSS

## Portable Text Structure

Portable Text is an array of blocks and marks:

```json theme={null}
[
  {
    "_type": "block",
    "style": "h2",
    "children": [
      {
        "_type": "span",
        "text": "Welcome to Sanity",
        "marks": []
      }
    ]
  },
  {
    "_type": "block",
    "style": "normal",
    "children": [
      {
        "_type": "span",
        "text": "This is a ",
        "marks": []
      },
      {
        "_type": "span",
        "text": "paragraph",
        "marks": ["strong"]
      },
      {
        "_type": "span",
        "text": " with formatting.",
        "marks": []
      }
    ]
  }
]
```

This represents:

```html theme={null}
<h2>Welcome to Sanity</h2>
<p>This is a <strong>paragraph</strong> with formatting.</p>
```

## Key Concepts

### Blocks

**Blocks** are the main content units:

* **Paragraphs** - `style: "normal"`
* **Headings** - `style: "h1"` through `style: "h6"`
* **Lists** - `listItem: "bullet"` or `listItem: "number"`
* **Custom blocks** - Images, code, embeds, etc.

### Marks

**Marks** are inline annotations:

* `strong` - Bold text
* `em` - Italic text
* `underline` - Underlined text
* `code` - Inline code
* `link` - Hyperlinks with `href`

### Spans

**Spans** are text segments within blocks, each with its own marks.

## How MigrateKit Converts HTML

When you migrate from Webflow, MigrateKit transforms HTML to Portable Text:

<Tabs>
  <Tab title="HTML Input">
    ```html theme={null}
    <h2>My Blog Post</h2>
    <p>This is <strong>important</strong> text with a <a href="/link">link</a>.</p>
    <ul>
      <li>First item</li>
      <li>Second item</li>
    </ul>
    ```
  </Tab>

  <Tab title="Portable Text Output">
    ```json theme={null}
    [
      {
        "_type": "block",
        "style": "h2",
        "children": [{"_type": "span", "text": "My Blog Post"}]
      },
      {
        "_type": "block",
        "style": "normal",
        "children": [
          {"_type": "span", "text": "This is "},
          {"_type": "span", "text": "important", "marks": ["strong"]},
          {"_type": "span", "text": " text with a "},
          {"_type": "span", "text": "link", "marks": [{"_type": "link", "href": "/link"}]},
          {"_type": "span", "text": "."}
        ]
      },
      {
        "_type": "block",
        "style": "normal",
        "listItem": "bullet",
        "children": [{"_type": "span", "text": "First item"}]
      },
      {
        "_type": "block",
        "style": "normal",
        "listItem": "bullet",
        "children": [{"_type": "span", "text": "Second item"}]
      }
    ]
    ```
  </Tab>
</Tabs>

Learn more: [HTML Conversion](/concepts/html-conversion)

## Benefits for Migration

### Preservation of Structure

HTML tags become semantic blocks:

| HTML       | Portable Text        | Benefit                          |
| ---------- | -------------------- | -------------------------------- |
| `<h2>`     | `style: "h2"`        | Heading semantics preserved      |
| `<strong>` | `marks: ["strong"]`  | Emphasis meaning, not just bold  |
| `<ul><li>` | `listItem: "bullet"` | List structure, not just bullets |

### Platform Flexibility

Render Portable Text differently on different platforms:

```tsx theme={null}
// Web - styled as H1
<h1 className="text-4xl">{heading}</h1>

// Mobile - styled as H2 for smaller screens
<h2 className="text-2xl">{heading}</h2>

// Email - inline styles
<h2 style="font-size: 24px">{heading}</h2>
```

All from the same Portable Text source!

### Querying and Filtering

Find content programmatically:

```groq theme={null}
// Find all documents with links to /pricing
*[_type == "post" && pt::text(body) match "*pricing*"]
```

You can't do this easily with HTML.

## Editing Portable Text

In Sanity Studio, Portable Text appears as a rich text editor:

Editors see familiar formatting options:

* Bold, italic, underline buttons
* Heading dropdown
* List buttons
* Link insertion
* Undo/redo

But behind the scenes, it's all stored as structured Portable Text.

## Custom Block Types

Portable Text isn't limited to text—you can embed custom content:

```json theme={null}
[
  {
    "_type": "block",
    "children": [{"_type": "span", "text": "Check out this image:"}]
  },
  {
    "_type": "image",
    "asset": {"_ref": "image-abc123-jpg"}
  },
  {
    "_type": "callout",
    "tone": "warning",
    "text": "Important notice!"
  }
]
```

This allows rich, interactive content while keeping structure.

## Why This Matters for Webflow Migrations

### From HTML Chaos to Structured Content

Webflow stores rich text as HTML—a mix of content, structure, and styling. Portable Text separates these concerns:

| Aspect          | HTML (Webflow)            | Portable Text (Sanity)          |
| --------------- | ------------------------- | ------------------------------- |
| **Content**     | Mixed with tags           | Pure text in `children`         |
| **Structure**   | Implicit in tags          | Explicit in `_type` and `style` |
| **Formatting**  | CSS classes/inline styles | Semantic marks                  |
| **Portability** | Web-specific              | Platform-agnostic               |

### Better Content Management

* **Cleaner** - No HTML tag soup
* **Safer** - No script injection risks
* **Flexible** - Render anywhere, any way
* **Searchable** - Query content semantically

## Common Questions

<AccordionGroup>
  <Accordion title="Can I still use HTML?">
    Yes! Sanity supports HTML in Portable Text through custom serializers. But you lose some benefits:

    * Can't query HTML content semantically
    * Platform-specific rendering is harder
    * Less structured

    MigrateKit converts HTML to Portable Text to give you maximum flexibility.
  </Accordion>

  <Accordion title="What if my HTML doesn't convert perfectly?">
    MigrateKit handles most common HTML tags, but complex structures may need manual cleanup:

    * Custom Webflow elements → Code blocks (review in Studio)
    * Nested formatting → Simplified to Portable Text rules
    * Unsupported tags → Wrapped for safety

    See [HTML Conversion](/concepts/html-conversion) for details.
  </Accordion>

  <Accordion title="Can I edit Portable Text as HTML?">
    In Sanity Studio, you edit using the rich text editor (WYSIWYG). To see the raw Portable Text JSON, use Sanity's Vision plugin.

    You typically don't need to edit Portable Text as JSON—the editor handles it.
  </Accordion>

  <Accordion title="Is Portable Text a Sanity-specific format?">
    Portable Text is an **open specification** created by Sanity. While Sanity uses it extensively, you can use Portable Text in any system. It's just JSON!
  </Accordion>
</AccordionGroup>


# Welcome to MigrateKit
Source: https://docs.contentwrap.io/introduction

Migrate Webflow content to Sanity CMS with automated CSV import. Built by ContentWrap.

## What is MigrateKit?

MigrateKit is a CSV migration tool built by [ContentWrap](https://contentwrap.io), the team behind enterprise Sanity implementations like Ramp's 1,500+ document migration.

Upload your Webflow CSV export, map fields to your Sanity schema, and import everything as drafts—ready for review before publishing.

<iframe title="YouTube video player" />

## Why MigrateKit?

Migrating CMS platforms manually is slow and error-prone. MigrateKit handles the tedious work:

* **Smart field mapping** - Visual interface to connect Webflow columns to Sanity fields
* **HTML to Portable Text** - Automatically converts rich text while preserving formatting
* **Asset migration** - Downloads images from Webflow and uploads them to Sanity
* **Safe drafts** - All imports create drafts, protecting your published content
* **Webflow-optimized** - Built specifically for Webflow's CSV export format

## How It Works

<Steps>
  <Step title="Export from Webflow">
    Download your collection as a CSV from Webflow CMS
  </Step>

  <Step title="Upload & Map">
    Upload the CSV and map Webflow fields to your Sanity schema
  </Step>

  <Step title="Connect Sanity">
    Link your Sanity project using your project ID and API token
  </Step>

  <Step title="Import">
    Review and execute the migration—all content imports as drafts
  </Step>
</Steps>

## Who Should Use MigrateKit?

<CardGroup>
  <Card title="Content Teams" icon="users">
    Migrate without technical expertise or custom scripts
  </Card>

  <Card title="Developers" icon="code">
    Save days of manual work and focus on building features
  </Card>

  <Card title="Agencies" icon="briefcase">
    Offer fast, reliable migration services to clients
  </Card>

  <Card title="Sanity Partners" icon="handshake">
    Streamline client onboarding and reduce project timelines
  </Card>
</CardGroup>

## Get Started

You'll need a **ContentWrap account** to use MigrateKit. Sign up for free, then navigate to **MigrateKit** in your sidebar or visit `/migratekit` to begin.

<CardGroup>
  <Card title="Prerequisites" icon="list-check" href="/prerequisites">
    What you need before starting
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Complete your first migration in under 10 minutes
  </Card>

  <Card title="Migration Overview" icon="map" href="/migration/overview">
    Full step-by-step migration roadmap
  </Card>
</CardGroup>


# Migration Overview
Source: https://docs.contentwrap.io/migration/overview

Understand MigrateKit's 4-step CSV migration process from Webflow to Sanity with automated field mapping and HTML conversion.

Use this page for the high-level flow. The canonical product behavior lives in the four step pages below.

## The 4-Step Process

MigrateKit's migration workflow is designed to be straightforward while giving you complete control over how your content transforms.

<Steps>
  <Step title="Connect Sanity">
    Add your Project ID, dataset, and API token in ContentWrap
  </Step>

  <Step title="Export from Webflow">
    Download your collection as a CSV file
  </Step>

  <Step title="Upload & Map Fields">
    Upload CSV and map Webflow columns to Sanity fields
  </Step>

  <Step title="Import & Verify">
    Execute migration and review drafts in Sanity Studio
  </Step>
</Steps>

## What Happens During Migration

<AccordionGroup>
  <Accordion title="Field Mapping">
    You define how Webflow data becomes Sanity documents:

    * Name your Sanity document type (e.g., `blogPost`)
    * Map each Webflow column to a Sanity field type
    * MigrateKit auto-suggests mappings based on data patterns
    * Skip system fields like `Collection ID` and `Item ID`
  </Accordion>

  <Accordion title="HTML to Portable Text Conversion">
    Rich text fields are automatically converted:

    * HTML tags become Portable Text blocks
    * Headings, paragraphs, lists preserved
    * Bold, italic, links maintained
    * Images embedded in content
    * Unsupported tags wrapped as code blocks

    Learn more: [HTML Conversion](/concepts/html-conversion)
  </Accordion>

  <Accordion title="Asset Migration">
    Images and files are handled automatically:

    * Downloads assets from Webflow CDN
    * Checks for duplicates (reuses existing)
    * Uploads to your Sanity project
    * Creates proper asset references
    * Reports upload status for each file

    Learn more: [Asset Handling](/concepts/field-mapping#image-fields)
  </Accordion>

  <Accordion title="Draft Mode Import">
    All content imports as drafts for safety:

    * Documents created with `drafts.` prefix
    * Published content remains untouched
    * Review and edit before publishing
    * Publish individually or in bulk
  </Accordion>
</AccordionGroup>

## Migration Flow

```mermaid theme={null}
graph LR
    A[Connect Sanity] --> B[Export Webflow CSV]
    B --> C[Upload CSV]
    C --> D[Map & Preview]
    D --> E[Import to Sanity]
    E --> F[Review Drafts]
    F --> G[Publish]
```

## Step-by-Step Guides

Follow detailed instructions for each phase:

<CardGroup>
  <Card title="Step 1: Connect Sanity" icon="link" href="/migration/step-1-connect-sanity">
    Link your Sanity project with API credentials
  </Card>

  <Card title="Step 2: Export" icon="download" href="/migration/step-2-export">
    How to export CSVs from Webflow correctly
  </Card>

  <Card title="Step 3: Upload & Map" icon="diagram-project" href="/migration/step-3-upload-map">
    Upload CSV and define field mappings
  </Card>

  <Card title="Step 4: Import" icon="cloud-arrow-up" href="/migration/step-4-import">
    Execute migration and verify results
  </Card>
</CardGroup>

## Best Practices

<Steps>
  <Step title="Start Small">
    * Test with a small collection (10-50 items)
    * Use a development dataset first
    * Verify the workflow works
    * Refine mappings before scaling
  </Step>

  <Step title="Keep Backups">
    * Save original CSV files
    * Don't delete Webflow data until verified
    * Export from Sanity for additional backup
  </Step>

  <Step title="Plan Your Schema">
    * Decide on document type names
    * Choose appropriate field types
    * Consider Sanity naming conventions
    * Think about future content structure
  </Step>

  <Step title="Review Before Publishing">
    * Check sample documents in Sanity
    * Verify Portable Text formatting
    * Confirm images loaded correctly
    * Test any links or embedded content
  </Step>
</Steps>

## Current Limitations

<Warning>
  **Single Collection Per Import**

  MigrateKit currently handles one collection at a time. For sites with multiple related collections:

  * Migrate independent collections first
  * Note relationships for manual recreation
  * Rebuild references in Sanity after import

  Multi-collection support with automatic reference resolution is on the roadmap.
</Warning>

<Info>
  **No Reference Field Support**

  Cross-collection references aren't automatically migrated. You'll need to manually recreate relationships in Sanity Studio after import.
</Info>

See [Limitations](/reference/limitations) for a complete list.

## Get Started

Ready to migrate? Choose your path:

<CardGroup>
  <Card title="Quickstart (10 min)" icon="rocket" href="/quickstart">
    Fast track migration guide
  </Card>

  <Card title="Prerequisites" icon="list-check" href="/prerequisites">
    What you need before starting
  </Card>
</CardGroup>

## Need Help?

<Card title="Troubleshooting" icon="wrench" href="/troubleshooting/common-issues">
  Common issues and solutions
</Card>


# Step 1: Connect Your Sanity Project
Source: https://docs.contentwrap.io/migration/step-1-connect-sanity

Start by linking ContentWrap to your Sanity project using your project ID, dataset name, and API token.

## Before You Begin

You'll need three pieces of information from your Sanity project:

1. **Project ID** - Found in your Sanity dashboard
2. **Dataset name** - Usually `production` or `development`
3. **API Token** - Must have **Editor** permissions

<Card title="Need help finding these?" icon="question-circle" href="/prerequisites#sanity-api-token">
  See prerequisites for detailed instructions
</Card>

## Find Your Sanity Credentials

### Get Your Project ID

<Steps>
  <Step title="Go to sanity.io/manage">
    Navigate to [sanity.io/manage](https://sanity.io/manage)
  </Step>

  <Step title="Select your project">
    Click on the project you want to migrate content into
  </Step>

  <Step title="Copy the Project ID">
    Find the Project ID in the project settings or URL

    Example: `abc123xyz`
  </Step>
</Steps>

### Choose Your Dataset

Your dataset is where content will be imported. Common options:

* **`production`** - Your live, published content
* **`development`** - Test/staging environment
* **`staging`** - Pre-production environment

<Tip>
  **First migration?** Use `development` or `staging` to test the migration safely before importing to `production`.
</Tip>

### Create an API Token

<Steps>
  <Step title="Go to API settings">
    In your Sanity project management console, click **API** in the sidebar
  </Step>

  <Step title="Click 'Add API Token'">
    Create a new token with these settings:

    * **Name**: MigrateKit Migration
    * **Permissions**: **Editor** (required for creating documents)
  </Step>

  <Step title="Copy the token immediately">
    Save it somewhere safe—you won't be able to see it again
  </Step>
</Steps>

## Connect in MigrateKit

### Add Your Sanity Project

If you haven't added a Sanity project yet:

<Steps>
  <Step title="Click 'Add Sanity Project'">
    In your ContentWrap dashboard (app.contentwrap.io), navigate to **Settings** → **Sanity Projects**
  </Step>

  <Step title="Enter your credentials">
    Fill in the form:

    * **Project ID**: Your Sanity project ID
    * **Dataset**: Your dataset name
    * **API Token**: The token you created
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify credentials

    <Check>
      You should see "Connection successful" with your project name
    </Check>
  </Step>

  <Step title="Save the project">
    Click **Save** to store your Sanity project in your account
  </Step>
</Steps>

### Select an Existing Project

If you've already connected a Sanity project:

<Steps>
  <Step title="Choose from dropdown">
    Select your project from the **Sanity Project** dropdown
  </Step>

  <Step title="Select dataset">
    Choose which dataset to import into
  </Step>
</Steps>

## Manage Document Types

After connecting a project, define which document types to use for migrations. You can add them manually or sync from your deployed Sanity dataset.

* **Add type manually**: Create a document type entry yourself
* **Sync types from Sanity**: Pull existing document types from your deployed dataset (recommended if schemas are already deployed)
* Shows counts per type (documents detected) and schema status

## Manage Schema Fields

For each document type, set up schema fields before mapping CSV columns. You can add fields manually or sync from Sanity.

* **Sync fields from Sanity**: Pull field definitions from deployed schema
* **Add field manually**: Define Sanity field name and type yourself
* MigrateKit attempts to infer types from existing values; you can override any field type

## Troubleshooting Connection Issues

<AccordionGroup>
  <Accordion title="'Invalid API token' error">
    **Causes:**

    * Token was copied incorrectly (extra spaces/characters)
    * Token doesn't have Editor permissions
    * Token was revoked or deleted

    **Fix:**

    * Create a new token with Editor permissions
    * Copy the entire token without extra spaces
    * Make sure you're using the correct project
  </Accordion>

  <Accordion title="'Project not found' error">
    **Causes:**

    * Project ID is incorrect
    * Typing error in Project ID
    * Using project name instead of ID

    **Fix:**

    * Double-check Project ID in your Sanity dashboard
    * Copy-paste instead of typing manually
    * Project ID is alphanumeric (e.g., `abc123xyz`), not the project name
  </Accordion>

  <Accordion title="'Dataset not found' error">
    **Causes:**

    * Dataset name is misspelled
    * Dataset doesn't exist in this project
    * Capitalization is wrong

    **Fix:**

    * Verify dataset name in Sanity project settings
    * Dataset names are case-sensitive
    * Create the dataset in Sanity if it doesn't exist
  </Accordion>

  <Accordion title="'Insufficient permissions' error">
    **Cause:** API token doesn't have Editor permissions

    **Fix:**

    * Create a new token with **Editor** role
    * Delete the old token for security
    * Update the token in your dashboard
  </Accordion>
</AccordionGroup>

## Security & Best Practices

### Protect Your API Token

* **Never commit tokens to git** - Add to `.gitignore`
* **Don't share publicly** - Treat like a password
* **Revoke unused tokens** - Delete tokens you're not using
* **Use environment variables** - For automation/scripts

### Token Management

* **Create project-specific tokens** - One per project/tool
* **Name tokens clearly** - E.g., "MigrateKit Migration - Production"
* **Rotate periodically** - Create new tokens, revoke old ones
* **Revoke if compromised** - Immediately delete and create new

### Multiple Projects

You can connect multiple Sanity projects to your ContentWrap account:

* Each project saved separately
* Switch between projects during migration
* Test in development, import to production


# Step 2: Export from Webflow
Source: https://docs.contentwrap.io/migration/step-2-export

Learn how to properly export your Webflow CMS collection as a CSV file for migration to Sanity using ContentWrap.

## Export Your Collection

<Steps>
  <Step title="Navigate to CMS Collections">
    In Webflow Designer or Editor, click **CMS** → **Collections**
  </Step>

  <Step title="Select your collection">
    Click the collection you want to migrate
  </Step>

  <Step title="Export as CSV">
    Click the settings icon (⚙️) → **Export** → **CSV file**

    Webflow downloads a file named `Collection Name.csv`
  </Step>

  <Step title="Save the original">
    Store the file safely and **make a backup copy**
  </Step>
</Steps>

<Check>
  You should now have a CSV file with all your collection's content, including all fields and metadata.
</Check>

## Critical: Don't Edit These Columns

MigrateKit relies on Webflow's system fields to prevent duplicates and track content. **Never modify or delete:**

<Warning>
  **Required Webflow Columns**

  * `Collection ID` - Identifies the source collection
  * `Item ID` - Unique identifier for each item (used to prevent duplicates)
  * `Locale ID` - Language/locale information

  If these columns are missing or modified, ContentWrap cannot properly track and update documents.
</Warning>

### Don't Rename Headers

Keep all column headers exactly as Webflow exports them:

| ❌ Wrong        | ✅ Correct    |
| -------------- | ------------ |
| `Post Title`   | `Name`       |
| `Article Body` | `Post Body`  |
| `Hero`         | `Main Image` |

Renaming headers breaks MigrateKit's auto-mapping feature.

## Safe Modifications

You CAN make these changes without breaking the migration:

<AccordionGroup>
  <Accordion title="Delete Entire Rows">
    Remove rows for content you don't want to migrate:

    * Draft items
    * Test content
    * Archived posts

    <Tip>
      **Better approach:** Import everything and delete unwanted drafts in Sanity instead. This gives you more flexibility.
    </Tip>
  </Accordion>

  <Accordion title="Remove Empty Columns">
    Delete columns that are completely empty (no data in any row):

    * Blank columns added by spreadsheet software
    * Trailing empty columns

    <Warning>
      Only delete if **every single row** is empty in that column!
    </Warning>
  </Accordion>

  <Accordion title="Remove Trailing Blank Rows">
    Delete empty rows at the end of the file after all your data
  </Accordion>
</AccordionGroup>

## Understanding Webflow CSV Structure

Knowing how Webflow formats different field types helps you plan your Sanity mapping:

### Text Fields

Plain text exports as simple strings:

```csv theme={null}
Name,Slug
My Blog Post,my-blog-post
```

### Rich Text (HTML)

Rich content exports as HTML in quoted cells:

```csv theme={null}
Post Body
"<h2>Introduction</h2><p>This post has <strong>formatting</strong>.</p>"
```

ContentWrap automatically converts this to Portable Text during import.

### Images

Images export as Webflow CDN URLs:

```csv theme={null}
Main Image
https://uploads-ssl.webflow.com/123abc/456def-image.jpg
```

ContentWrap downloads these and uploads them to your Sanity project.

\###Multi-Image Fields

Multiple images are comma-separated:

```csv theme={null}
Gallery
"https://cdn.webflow.com/img1.jpg,https://cdn.webflow.com/img2.jpg"
```

### Dates

Dates export in ISO format:

```csv theme={null}
Published Date
2024-01-15T10:30:00.000Z
```

<Warning>
  **Excel will corrupt dates!** Excel auto-formats dates, changing `2024-01-15T10:30:00.000Z` to `1/15/2024`. This breaks the import.

  **Solution:** Use Google Sheets or open CSVs in a text editor. If you must use Excel, import as text.
</Warning>

### Booleans

Checkboxes export as text:

```csv theme={null}
Featured
true
```

MigrateKit converts `"true"`, `"yes"`, and `"1"` to `true`.

### Reference Fields

<Info>
  **Not Currently Supported**

  Reference fields export but can't be automatically imported. You'll need to manually recreate relationships in Sanity after migration.

  See [Limitations](/reference/limitations) for details.
</Info>

## Common Issues

<AccordionGroup>
  <Accordion title="Special characters look broken">
    **Problem:** Seeing `é` instead of `é` or `’` instead of `'`.

    **Cause:** Encoding issue (not UTF-8).

    **Solution:**

    * Re-export from Webflow
    * MigrateKit handles UTF-8, UTF-16, and most encodings
    * If it persists, the source data in Webflow may be corrupted
  </Accordion>

  <Accordion title="Excel changed my data">
    **Problem:** Excel removed leading zeros, changed dates, or modified large numbers.

    **Solution:**

    * Don't open CSVs in Excel
    * Use Google Sheets or LibreOffice Calc
    * OR import in Excel as text: **Data** → **From Text/CSV** → set columns to **Text** format
  </Accordion>

  <Accordion title="CSV has weird line breaks">
    **Problem:** File looks broken in text editor with strange line endings.

    **Solution:** This is normal! CSVs can use different line ending formats (Windows vs. Mac vs. Unix). MigrateKit handles all formats correctly.
  </Accordion>

  <Accordion title="Commas in content break columns">
    **Problem:** Content with commas creates extra columns.

    **Solution:** This shouldn't happen—Webflow wraps fields containing commas in quotes. If you see this, the CSV may be corrupted. Re-export from Webflow.
  </Accordion>
</AccordionGroup>

## Pre-Upload Checklist

Before uploading to ContentWrap, verify:

* [ ] First row contains original Webflow headers (not renamed)
* [ ] `Collection ID`, `Item ID`, and `Locale ID` columns present
* [ ] No obviously corrupted data (garbled characters)
* [ ] Dates are properly formatted (if visible)
* [ ] Image URLs are complete (start with `https://`)
* [ ] File saved with `.csv` extension
* [ ] Backup copy created


# Step 3: Upload & Map Fields
Source: https://docs.contentwrap.io/migration/step-3-upload-map

Upload your Webflow CSV to MigrateKit and map fields to your Sanity schema with intelligent auto-suggestions and validation.

## Upload Your CSV

<Steps>
  <Step title="Access MigrateKit">
    Navigate to **MigrateKit** in your ContentWrap dashboard (app.contentwrap.io) or visit `/migratekit`
  </Step>

  <Step title="Upload your file">
    Drag and drop your CSV or click to browse

    <Check>
      MigrateKit detects Webflow format and shows a preview
    </Check>
  </Step>

  <Step title="Review the preview">
    Verify:

    * Total rows matches expectations
    * All columns are detected
    * Sample data looks correct
  </Step>
</Steps>

## Understanding the Mapping Interface

The mapping screen has two panels:

<CardGroup>
  <Card title="Left: Sanity Schema" icon="diagram-project">
    Define your Sanity structure:

    * Document type name
    * Field names and types
    * Required field settings
  </Card>

  <Card title="Right: Webflow Data" icon="table-columns">
    Your CSV from Webflow:

    * Column names
    * Sample data
    * Detected data types
  </Card>
</CardGroup>

## Name Your Document Type

First, choose a name for your Sanity document type:

<Tabs>
  <Tab title="Good Names">
    * `blogPost`
    * `article`
    * `author`
    * `product`

    <Tip>
      Use **camelCase**: lowercase start, capitalize subsequent words, no spaces or hyphens
    </Tip>
  </Tab>

  <Tab title="Invalid Names">
    * `Blog Post` ❌ (space)
    * `blog-post` ❌ (hyphen)
    * `123post` ❌ (starts with number)
    * `BlogPost` ⚠️ (works but `blogPost` preferred)
  </Tab>
</Tabs>

## Map Your Fields

Connect each Webflow column to a Sanity field:

### Auto-Mapping

MigrateKit suggests mappings based on:

* Column names (e.g., `Name` → `title`)
* Data types detected in your CSV
* Common Webflow patterns

Review suggestions and adjust as needed.

### Manual Mapping

For each Webflow column:

<Steps>
  <Step title="Select the column">
    Click a Webflow column on the right to see sample data
  </Step>

  <Step title="Create or select a Sanity field">
    On the left, click **+ Add Field** or select an existing field
  </Step>

  <Step title="Configure the field">
    Set:

    * **Field name**: Sanity field name (e.g., `content`, `heroImage`)
    * **Field type**: Choose from Sanity types
    * **Required**: Whether field must have a value
  </Step>
</Steps>

### Quick Field Type Reference

| Webflow Column Type | Sanity Field Type | Notes              |
| ------------------- | ----------------- | ------------------ |
| Name, Title         | `string`          | Short text         |
| Rich Text, Body     | `portableText`    | HTML auto-converts |
| Main Image          | `image`           | Single image       |
| Slug                | `slug`            | URL-friendly ID    |
| Published Date      | `datetime`        | With time          |
| Price, Count        | `number`          | Numeric values     |
| Featured, Active    | `boolean`         | True/false         |
| Website             | `url`             | Web URLs           |

## Field Configuration Options

### Required Fields

Mark fields as required if they must have a value:

<Warning>
  **Important:** If a required field has empty values in some CSV rows, those rows will fail to import
</Warning>

### Field Renaming

Use different names in Sanity than Webflow:

| Webflow    | → | Sanity    | Why              |
| ---------- | - | --------- | ---------------- |
| Name       | → | title     | More semantic    |
| Post Body  | → | content   | Cleaner          |
| Main Image | → | heroImage | More descriptive |

### Fields to Skip

Don't map these Webflow columns (MigrateKit uses them internally):

* `Collection ID`
* `Item ID`
* `Locale ID`

Optionally skip Webflow timestamps (Sanity manages its own):

* `Created On` (Sanity creates `_createdAt`)
* `Updated On` (Sanity creates `_updatedAt`)
* `Published On` (Sanity creates `_publishedAt`)

<Tip>
  You CAN map these to custom fields if you want to preserve original Webflow dates
</Tip>

## Special Field Types

<AccordionGroup>
  <Accordion title="Portable Text (Rich Content)">
    **Use for:** Webflow rich text fields with HTML

    MigrateKit automatically converts:

    * Headings (H1-H6)
    * Paragraphs and line breaks
    * Bold, italic, underline
    * Lists (ordered and unordered)
    * Links
    * Embedded images

    Learn more: [HTML Conversion](/concepts/html-conversion)
  </Accordion>

  <Accordion title="Image Fields">
    **Use for:** Webflow image columns

    During import, MigrateKit:

    1. Downloads images from Webflow CDN
    2. Checks for duplicates (reuses if exists)
    3. Uploads to your Sanity project
    4. Creates proper image references
  </Accordion>

  <Accordion title="Slug Fields">
    **Use for:** Webflow slug column

    MigrateKit:

    * Sanitizes values (removes special characters)
    * Formats for Sanity's slug type (`{current: "value"}`)
    * Preserves URL-friendly format
  </Accordion>

  <Accordion title="Arrays">
    **Use for:** Comma-separated values (tags, categories, multiple images)

    Map to `array` and specify item type:

    * Array of strings
    * Array of images
    * Array of numbers
  </Accordion>
</AccordionGroup>

## Validation

MigrateKit validates your mappings before import:

<AccordionGroup>
  <Accordion title="Schema Validation">
    * Document type name is valid
    * No duplicate field names
    * Field types match data
    * Required fields are mapped
  </Accordion>

  <Accordion title="Data Validation">
    * Values can convert to target types
    * Required fields have data
    * Dates are parseable
    * Numbers are numeric
    * URLs are valid
  </Accordion>

  <Accordion title="Preview">
    Review sample transformed documents:

    * First 3-5 documents shown
    * Check Portable Text rendering
    * Verify image references
    * Confirm data looks correct
  </Accordion>
</AccordionGroup>

## Common Validation Issues

<Warning>
  **"Field type mismatch"**

  Data doesn't match chosen type (e.g., text in a number field).

  **Fix:** Change field type or clean data in CSV.
</Warning>

<Warning>
  **"Required field has empty values"**

  Some rows missing data for a required field.

  **Fix:** Make field optional, fill missing values, or skip those rows.
</Warning>

<Warning>
  **"Invalid Portable Text"**

  HTML couldn't be converted properly.

  **Fix:** Check HTML for malformed tags or unsupported structures. See [Troubleshooting](/troubleshooting/common-issues#html-conversion-errors).
</Warning>


# Step 4: Import & Verify
Source: https://docs.contentwrap.io/migration/step-4-import

Execute your migration, monitor progress, and verify imported content in Sanity Studio before publishing.

## Final Review

Before starting the import, review your configuration:

<Steps>
  <Step title="Check the preview">
    MigrateKit shows sample documents in Sanity format:

    * Review 3-5 sample documents
    * Check Portable Text rendering
    * Verify image references
    * Confirm field mappings look correct
  </Step>

  <Step title="Review import summary">
    Confirm:

    * Total documents to import
    * Number of assets to upload
    * Target Sanity project and dataset
    * Any validation warnings
  </Step>

  <Step title="Check for warnings">
    Address any yellow warning indicators:

    * Missing recommended fields
    * Potential data type issues
    * Large file sizes
  </Step>
</Steps>

<Warning>
  **Address errors before importing**

  Red error messages will block the import. Fix these issues before proceeding:

  * Required fields with missing data
  * Invalid field types
  * Malformed HTML
  * Connection issues

  See [Troubleshooting](/troubleshooting/common-issues) for help.
</Warning>

## Execute the Import

<Steps>
  <Step title="Click 'Import to Sanity'">
    Start the migration process

    <Info>
      All documents are created as **drafts** (with `drafts.` prefix). Your published content stays safe.
    </Info>
  </Step>

  <Step title="Monitor progress">
    Watch real-time updates:

    * Documents created: XX / YY
    * Assets uploaded: XX / YY
    * Processing time estimate
    * Current operation status
  </Step>

  <Step title="Review results">
    When complete, you'll see:

    * Total documents imported
    * Assets uploaded vs. reused
    * Any warnings or errors
    * Link to view drafts in Sanity
  </Step>
</Steps>

## Understanding Import Status

<Tabs>
  <Tab title="Success">
    **Green checkmark** - Document imported successfully

    The document is now a draft in your Sanity project, ready for review.
  </Tab>

  <Tab title="Warning">
    **Yellow triangle** - Imported with warnings

    Document was created but has potential issues:

    * Some HTML didn't convert perfectly
    * Optional fields were empty
    * Asset upload was slow

    Review these documents in Sanity to ensure they look correct.
  </Tab>

  <Tab title="Error">
    **Red X** - Import failed

    Common causes:

    * Required field had empty value
    * Data type mismatch
    * Invalid Portable Text
    * Asset download failed

    See the error details and fix the issue before re-importing.
  </Tab>
</Tabs>

## Asset Upload Details

MigrateKit handles image and file uploads automatically:

### How Assets Are Processed

<Steps>
  <Step title="Download from Webflow">
    Fetches assets from Webflow CDN URLs in your CSV
  </Step>

  <Step title="Check for duplicates">
    Uses image hash to detect if asset already exists in your Sanity project
  </Step>

  <Step title="Upload or reuse">
    * **Upload**: New assets are uploaded to Sanity
    * **Reuse**: Existing assets are referenced (saves time and space)
  </Step>

  <Step title="Create references">
    Links uploaded assets to the appropriate document fields
  </Step>
</Steps>

### Asset Upload Statuses

* **Uploaded** - New asset uploaded to Sanity
* **Reused** - Existing asset found and referenced
* **Failed** - Upload failed (network error, quota exceeded, invalid URL)

<Info>
  Failed asset uploads don't block the document import. Documents import with missing image references, and you can manually upload assets later.
</Info>

## Verify in Sanity Studio

<Steps>
  <Step title="Open Sanity Studio">
    Navigate to your Sanity Studio (usually `yourproject.sanity.studio`)
  </Step>

  <Step title="View drafts">
    Click the **Drafts** filter to see imported documents
  </Step>

  <Step title="Check random samples">
    Review several documents for:

    * **Content accuracy** - Text matches Webflow source
    * **Formatting** - Portable Text looks correct (headings, lists, bold/italic)
    * **Images** - All images loaded and display properly
    * **Links** - Links are clickable and point to correct URLs
  </Step>

  <Step title="Test Portable Text">
    Open documents with rich text content:

    * Headings render at correct levels
    * Paragraph spacing looks natural
    * Lists are formatted properly
    * Bold, italic, underline preserved
  </Step>
</Steps>

## Common Post-Import Tasks

<AccordionGroup>
  <Accordion title="Fix embed code blocks">
    Webflow embeds import as code blocks for safety. Review and replace with Sanity-compatible alternatives:

    * YouTube embeds → Sanity YouTube plugin
    * Custom scripts → Sanity-safe implementations
    * Iframes → Appropriate Sanity component

    Learn more: [HTML Conversion](/concepts/html-conversion)
  </Accordion>

  <Accordion title="Recreate references">
    Since reference fields aren't migrated automatically:

    1. Note which documents should reference others
    2. Manually link references in Sanity Studio
    3. Consider creating a checklist before migration
  </Accordion>

  <Accordion title="Adjust formatting">
    Fine-tune Portable Text if needed:

    * Adjust heading levels
    * Add spacing between sections
    * Clean up formatting quirks from HTML conversion
  </Accordion>

  <Accordion title="Optimize images">
    Consider:

    * Adding alt text for accessibility
    * Cropping or resizing images
    * Adding captions or credits
  </Accordion>
</AccordionGroup>

## Publish Your Content

Once you've verified everything looks correct:

<Steps>
  <Step title="Select documents to publish">
    In Sanity Studio, choose documents from the drafts section
  </Step>

  <Step title="Publish individually">
    Click **Publish** on each document

    Or:
  </Step>

  <Step title="Bulk publish">
    Select multiple documents and publish in batch

    <Tip>
      Start with a small batch to ensure everything works before publishing all content
    </Tip>
  </Step>
</Steps>

<Check>
  Published documents are now live in your Sanity dataset!
</Check>

## If Something Went Wrong

<AccordionGroup>
  <Accordion title="Some documents didn't import">
    Check the import report for specific errors:

    * Fix issues in original CSV
    * Adjust field mappings if needed
    * Re-upload and import just the failed rows

    See [Troubleshooting: Import Errors](/troubleshooting/common-issues#import-errors)
  </Accordion>

  <Accordion title="Portable Text looks wrong">
    Common causes:

    * Complex HTML structures MigrateKit couldn't convert
    * Nested formatting that doesn't map to Portable Text
    * Custom Webflow elements

    **Fix:** Manually edit in Sanity Studio or see [HTML Conversion Issues](/troubleshooting/common-issues#html-conversion-errors)
  </Accordion>

  <Accordion title="Images are missing">
    Check:

    * Asset upload report for failures
    * Original Webflow CSV has valid image URLs
    * Sanity asset quota not exceeded

    You can manually upload missing images in Sanity Studio.
  </Accordion>

  <Accordion title="Need to re-import">
    To start over:

    1. Delete drafts in Sanity Studio (select all → delete)
    2. Adjust your field mappings in MigrateKit
    3. Re-import the CSV

    MigrateKit uses `Item ID` to update existing documents instead of creating duplicates.
  </Accordion>
</AccordionGroup>


# Prerequisites
Source: https://docs.contentwrap.io/prerequisites

Everything you need before migrating your Webflow content to Sanity with ContentWrap's CSV migration tool.

## What You'll Need

Before starting your migration, make sure you have:

### 1. Webflow Access

* **CMS Collections** - At least one collection with content to migrate
* **Export permissions** - Ability to export collections as CSV files
* **Admin or Editor role** - Required to access CMS export features

### 2. Sanity Project

You need an active Sanity project with at least one dataset.

* Project ID
* Dataset name (e.g., `production` or `staging`)
* Schema deployed to that dataset (required for v1)

See the Connect step for how to grab these in [sanity.io/manage](https://www.sanity.io/manage).

### 3. Sanity API Token

You'll need an API token with write permissions:

* **Sanity Free:** Editor
* **Growth/Enterprise:** Editor or Developer (both read/write)

Create and copy your token from **API → Add API token** in [sanity.io/manage](https://www.sanity.io/manage). Detailed steps live in the Connect guide.

<Warning>
  **Important:** Use a permission with **read/write** access (Editor or Developer). **Viewer** is read-only and cannot import content.
</Warning>

### 4. ContentWrap Account

Sign up for a free ContentWrap account to access MigrateKit:

<Card title="Sign Up" icon="user-plus" href="https://app.contentwrap.io/auth/sign-up">
  Create your ContentWrap account
</Card>

<Info>
  ContentWrap is the platform that powers MigrateKit. Your account gives you access to migration tools and, optionally, white-glove migration services.
</Info>

### 5. Add Your Sanity Project in ContentWrap

In ContentWrap, open the **Projects** tab and add:

* **Project ID** (copied from Sanity project header)
* **Dataset** (e.g., `production`, `staging`, or `development`)
* **API Token** (Editor or Developer)

Make sure the dataset already exists in Sanity (**Settings** → **Datasets**) and your schema is deployed to that dataset.

<Info>
  You can add multiple projects in ContentWrap. Select the project/dataset you want active during migration.
</Info>

## Optional But Recommended

### Test Dataset

For your first migration, use a Sanity **development** or **staging** dataset instead of production:

* Test the migration workflow without risk
* Refine field mappings and see results
* Delete and retry if needed
* Move to production once confident

### CSV Editor

While not required, a good CSV editor helps you review exports:

* **Google Sheets** - Free, handles UTF-8 well
* **LibreOffice Calc** - Free, better than Excel for CSVs
* **VS Code** - View raw CSV structure

<Warning>
  **Avoid Microsoft Excel** - It auto-formats dates and can corrupt CSV data. If you must use Excel, import CSVs as text to prevent formatting issues.
</Warning>

## Understanding Webflow Collection Structure

Familiarize yourself with your Webflow CMS collections:

| Element    | Description                | Example                       |
| ---------- | -------------------------- | ----------------------------- |
| Collection | A content type in Webflow  | Blog Posts, Authors, Products |
| Item       | A single piece of content  | One blog post, one author     |
| Field      | A property of an item      | Title, Body, Image, Date      |
| Reference  | Link to another collection | Post → Author relationship    |

<Info>
  **Reference fields** are not currently supported in ContentWrap. You'll need to recreate relationships in Sanity after migration. Multi-collection support with reference resolution is on the roadmap.
</Info>

## Ready to Start?

Once you have everything above, you're ready to begin:

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Migrate your first collection in 10 minutes
  </Card>

  <Card title="Migration Guide" icon="map" href="/migration/overview">
    Detailed step-by-step instructions
  </Card>
</CardGroup>

## Need Help Getting Set Up?

<AccordionGroup>
  <Accordion title="I don't have a Sanity project yet">
    No problem! Follow Sanity's [Getting Started guide](https://www.sanity.io/docs/getting-started) to create your first project. It takes about 5 minutes.
  </Accordion>

  <Accordion title="I'm not sure which dataset to use">
    If your Sanity project is new, use the `production` dataset. If you already have content in production, create a `staging` or `development` dataset for testing migrations.
  </Accordion>

  <Accordion title="Can I migrate without a Sanity schema?">
    Not in v1. Your schema must already be deployed to the target dataset so ContentWrap can read it during mapping and import.
  </Accordion>

  <Accordion title="What if my API token expires?">
    Sanity API tokens don't expire by default. If you revoke a token, create a new one with the same permissions and update it in ContentWrap.
  </Accordion>
</AccordionGroup>


# Quickstart Guide
Source: https://docs.contentwrap.io/quickstart

Migrate your first Webflow collection to Sanity in 10 minutes with this step-by-step quickstart guide.

This guide is the condensed path to your first migration. For canonical, detailed behavior and edge cases, use the [Migration Guide steps](/migration/step-1-export).

## Before You Begin

Make sure you have:

* A Webflow collection to export
* A Sanity project with dataset (or ready to create one)
* A Sanity API token with Editor permissions
* A ContentWrap account

<Card title="Need setup help?" icon="list-check" href="/prerequisites">
  See prerequisites for detailed requirements
</Card>

## Step 1: Export from Webflow

<Steps>
  <Step title="Open Webflow CMS">
    Navigate to your Webflow project and click **CMS** → **Collections**
  </Step>

  <Step title="Select a collection">
    Choose a collection to migrate
  </Step>

  <Step title="Export as CSV">
    Click the settings icon (⚙️) → **Export** → **CSV file**
  </Step>
</Steps>

<Warning>
  **Don't edit the CSV!** Keep all columns and headers exactly as Webflow exports them, especially `Collection ID`, `Item ID`, and `Locale ID`.
</Warning>

## Step 2: Upload to MigrateKit

<Steps>
  <Step title="Sign in">
    Go to [app.contentwrap.io](https://app.contentwrap.io) and sign in
  </Step>

  <Step title="Open MigrateKit">
    Click **MigrateKit** in the sidebar or navigate to `/migratekit`
  </Step>

  <Step title="Upload your CSV">
    Drag and drop your Webflow CSV or click to browse
  </Step>
</Steps>

<Check>
  MigrateKit automatically detects your Webflow structure and shows a preview
</Check>

## Step 3: Map Fields

Define how Webflow content becomes Sanity documents:

<Steps>
  <Step title="Name your document type">
    Enter a Sanity-compatible name (e.g., `blogPost`, `article`, `product`)

    <Tip>
      Use camelCase with no spaces: `blogPost` ✓ not `Blog Post` ✗
    </Tip>
  </Step>

  <Step title="Map your fields">
    For each Webflow column, select a Sanity field type:

    | Webflow Column | Sanity Type    | Notes               |
    | -------------- | -------------- | ------------------- |
    | Name/Title     | `string`       | Plain text          |
    | Post Body      | `portableText` | HTML auto-converts  |
    | Main Image     | `image`        | Downloads & uploads |
    | Slug           | `slug`         | URL-friendly ID     |
    | Published Date | `datetime`     | ISO date format     |
  </Step>

  <Step title="Skip system fields">
    Don't map: `Collection ID`, `Item ID`, `Locale ID` (ContentWrap uses these internally)
  </Step>
</Steps>

<Info>
  MigrateKit auto-suggests mappings based on column names and data types. Review and adjust as needed.
</Info>

## Step 4: Connect Sanity

<Steps>
  <Step title="Enter project details">
    You'll need three things:

    * **Project ID** - Found in your Sanity dashboard
    * **Dataset** - Usually `production` or `development`
    * **API Token** - Must have **Editor** permissions
  </Step>

  <Step title="Test connection">
    Click **Test Connection** to verify credentials
  </Step>
</Steps>

<Tip>
  **First migration?** Use a test dataset like `development` to safely try the migration before importing to production.
</Tip>

## Step 5: Import

<Steps>
  <Step title="Review the preview">
    Check sample documents to ensure:

    * Field mappings look correct
    * Portable Text renders properly
    * Images are referenced
  </Step>

  <Step title="Start import">
    Click **Import to Sanity**

    <Info>
      All documents import as **drafts**—your published content stays safe
    </Info>
  </Step>

  <Step title="Monitor progress">
    Watch the real-time progress:

    * Documents created
    * Assets uploaded
    * Warnings or errors
  </Step>
</Steps>

## Step 6: Verify in Sanity

<Steps>
  <Step title="Open Sanity Studio">
    Navigate to your Sanity Studio (usually `yourproject.sanity.studio`)
  </Step>

  <Step title="Check drafts">
    Review migrated documents in the drafts section

    * Check content accuracy
    * Verify formatting
    * Confirm images loaded
  </Step>

  <Step title="Publish when ready">
    Publish documents individually or in bulk
  </Step>
</Steps>

## What's Next?

<CardGroup>
  <Card title="Full Migration Guide" icon="map" href="/migration/overview">
    Complete walkthrough with advanced options
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting/common-issues">
    Common issues and how to fix them
  </Card>

  <Card title="Understanding Portable Text" icon="code" href="/concepts/portable-text">
    How HTML converts to Portable Text
  </Card>
</CardGroup>

## Need Help?

<AccordionGroup>
  <Accordion title="The CSV upload failed">
    Check that your file:

    * Is a valid CSV (not XLSX or other format)
    * Has all original Webflow columns
    * Isn't corrupted or edited in Excel

    See [CSV troubleshooting](/troubleshooting/common-issues#csv-issues) for more help.
  </Accordion>

  <Accordion title="Portable Text looks wrong">
    This usually happens with complex HTML. MigrateKit converts most common tags, but some structures may need manual cleanup in Sanity.

    Learn more: [HTML Conversion](/concepts/html-conversion)
  </Accordion>

  <Accordion title="Images didn't upload">
    Image upload failures typically occur due to:

    * Invalid image URLs in your CSV
    * Network timeouts for large files
    * Sanity asset quota limits

    The import report shows which assets failed—you can re-upload them manually.
  </Accordion>

  <Accordion title="Some rows failed to import">
    Check the error messages for specific issues:

    * Required fields with missing values
    * Invalid data types (text in number fields)
    * Malformed dates or slugs

    Fix the issues and re-import just those rows.
  </Accordion>
</AccordionGroup>

<Card title="Contact Support" icon="envelope" href="mailto:support@contentwrap.io">
  Still stuck? Email us at [support@contentwrap.io](mailto:support@contentwrap.io)
</Card>


# Current Limitations & Roadmap
Source: https://docs.contentwrap.io/reference/limitations

Understand MigrateKit's current capabilities, known limitations, and upcoming features for Webflow to Sanity migrations.

## What's Supported Today

MigrateKit currently provides robust CSV-based migration from Webflow to Sanity:

<CardGroup>
  <Card title="CSV Upload" icon="check">
    Full support for Webflow CSV exports
  </Card>

  <Card title="Field Mapping" icon="check">
    Visual interface with auto-suggestions
  </Card>

  <Card title="HTML Conversion" icon="check">
    Comprehensive HTML to Portable Text
  </Card>

  <Card title="Asset Migration" icon="check">
    Images and files with deduplication
  </Card>

  <Card title="Type Coercion" icon="check">
    String, number, date, boolean, slug
  </Card>

  <Card title="Draft Mode" icon="check">
    All imports create safe drafts
  </Card>
</CardGroup>

## Current Limitations

### Single Collection Per Import

**Status:** ⚠️ **Limitation**

MigrateKit handles one Webflow collection at a time.

**Impact:**

* Must import collections separately
* Can't resolve references automatically
* Manual reference recreation required

**Workaround:**

1. Import independent collections first
2. Note relationship data
3. Import dependent collections
4. Manually link references in Sanity Studio

**Future:** Multi-collection support with automatic reference resolution is on the roadmap.

***

### No Reference Field Support

**Status:** ⚠️ **Limitation**

Cross-collection relationships aren't migrated automatically.

**Impact:**

* Reference fields can't be mapped
* Relationships must be recreated manually
* Multi-reference fields not supported

**Workaround:**

* Map reference columns as `string` (preserves ID/slug)
* After import, manually link references in Sanity Studio
* Document relationships before migration for easy recreation

**Example:**

Webflow: `Post → Author` (reference field)
MigrateKit: Map `author` as `string` (stores author ID)
After import: Convert to Sanity reference manually

**Future:** Reference resolution with deterministic ID matching coming soon.

***

### Webflow-Only Sources

**Status:** ⚠️ **Limitation**

MigrateKit is optimized for Webflow CSV exports.

**Impact:**

* Other CMS exports (WordPress, Contentful, etc.) not officially supported
* May work if CSV structure is similar, but no guarantees

**Future:** WordPress and other CMS support planned for Q3 2025.

***

### System Timestamps

**Status:** ⚠️ **Limitation**

Sanity controls `_createdAt`, `_updatedAt`, and `_publishedAt` fields.

**Impact:**

* Can't preserve original Webflow timestamps in system fields
* Imported documents get new Sanity timestamps

**Workaround:**

* Map Webflow timestamps to custom fields:
  * `Created On` → `webflowCreatedAt`
  * `Published On` → `webflowPublishedAt`
* Preserve original dates for reference

**Note:** This is a Sanity limitation, not a MigrateKit limitation.

***

### No Schema Generation

**Status:** ⚠️ **Limitation (MVP)**

You define schema during mapping, but MigrateKit doesn't generate Sanity schema files.

**Impact:**

* Must manually create schema in Sanity Studio if you want:
  * Custom validation
  * Field configurations
  * UI customizations

**Current approach:**

* Map fields in MigrateKit (defines structure)
* Import creates documents
* Manually create matching schema in Sanity if needed

**Future:** Automated schema generation coming soon—MigrateKit will create Sanity schema files based on your mapping.

***

### Limited Batch Size

**Status:** ⚠️ **Practical Limitation**

Very large imports (>5,000 rows) may be slow.

**Impact:**

* Large migrations take longer
* Memory/timeout constraints for massive datasets

**Workaround:**

* Split large collections into batches
* Import during off-peak hours
* Consider ContentWrap Pro for larger limits

**Note:** Most Webflow collections are well under this limit.

***

## Feature Comparison

| Feature                       | Status         | Notes                               |
| ----------------------------- | -------------- | ----------------------------------- |
| CSV Upload & Mapping          | ✅ Available    | Full support                        |
| HTML → Portable Text          | ✅ Available    | Comprehensive tag support           |
| Field Type Coercion           | ✅ Available    | All common types                    |
| Asset Upload (Images & Files) | ✅ Available    | With deduplication                  |
| Draft Mode Import             | ✅ Available    | Safe by default                     |
| Deterministic IDs             | ✅ Available    | Uses Webflow Item ID                |
| **Reference Resolution**      | 🚧 Coming Soon | Automatic relationship linking      |
| **Multi-Collection Import**   | 🚧 Coming Soon | Import related collections together |
| **Schema Generation**         | 🚧 Coming Soon | Auto-generate Sanity schemas        |
| **WordPress Support**         | 📋 Planned     | Q3 2025                             |
| **Contentful Support**        | 📋 Planned     | Q4 2025                             |

## Roadmap

### Phase 1: Core Migration ✅ (Complete)

* CSV upload and parsing
* Visual field mapping
* HTML to Portable Text conversion
* Asset migration
* Draft mode import
* Webflow-optimized workflow

### Phase 2: References & Multi-Collection 🚧 (In Progress)

* Automatic reference resolution using deterministic IDs
* Multi-collection import in single workflow
* Relationship mapping interface
* Cross-collection validation

### Phase 3: Schema & Automation 📋 (Planned)

* Automated Sanity schema generation
* Export schema files for Studio
* Schema validation and best practices
* Reusable mapping templates

### Phase 4: Multi-CMS Support 📋 (Planned)

* WordPress CSV/XML import
* Contentful export support
* Generic CSV import (any CMS)
* Custom mapping for non-standard formats

### Phase 5: Advanced Features 📋 (Future)

* Incremental sync (update changed content)
* Scheduled migrations
* Migration preview/rollback
* Bulk operations API
* Custom transformation scripts

## Get Updates

<Info>
  **Stay informed:** New features and updates are announced in the [changelog](/changelog).
</Info>

## Working Within Current Limitations

### Best Practices

<AccordionGroup>
  <Accordion title="Plan for manual reference work">
    **Before migration:**

    * Document all relationships in your Webflow collections
    * Note which fields reference other collections
    * Create a checklist for manual linking

    **After migration:**

    * Use Sanity Studio's reference picker
    * Link relationships systematically
    * Verify all links are correct
  </Accordion>

  <Accordion title="Test with small collections first">
    * Start with a simple, independent collection (10-50 items)
    * Verify the workflow works
    * Identify any edge cases
    * Then scale to larger collections
  </Accordion>

  <Accordion title="Use development dataset">
    * Import to `development` or `staging` first
    * Test thoroughly
    * Delete and retry if needed
    * Only import to `production` when confident
  </Accordion>

  <Accordion title="Document your process">
    * Screenshot field mappings
    * Note any manual steps required
    * Save mapping decisions for future imports
    * Create a migration checklist
  </Accordion>
</AccordionGroup>

## Request Features

Have a specific use case or need? We'd love to hear from you:

<Card title="Feature Requests" icon="lightbulb" href="mailto:support@contentwrap.io?subject=Feature Request">
  Email [support@contentwrap.io](mailto:support@contentwrap.io) with your ideas
</Card>

## Enterprise Support

Need capabilities beyond current limits?

<Info>
  **Enterprise services available:**

  * Schema generation for your migrations
  * Manual reference resolution
  * Custom multi-collection workflows
  * Assisted migrations for complex sites

  Contact [support@contentwrap.io](mailto:support@contentwrap.io) for details.
</Info>


# Troubleshooting Common Issues
Source: https://docs.contentwrap.io/troubleshooting/common-issues

Solutions to common problems when migrating Webflow content to Sanity with MigrateKit.

## CSV Upload Issues

<AccordionGroup>
  <Accordion title="CSV upload failed">
    **Symptoms:** Error message when uploading CSV file

    **Common causes:**

    * File is not a valid CSV (e.g., XLSX, TXT with wrong extension)
    * File is corrupted or has encoding issues
    * File is too large (>10MB)

    **Solutions:**

    * Verify file extension is `.csv`
    * Re-export from Webflow
    * Open in text editor to check for corruption
    * Split large CSVs into smaller batches
  </Accordion>

  <Accordion title="CSV headers look wrong">
    **Symptoms:** Column names are garbled or incorrect in preview

    **Causes:**

    * CSV opened and saved in Excel (changed encoding)
    * File has BOM (Byte Order Mark)
    * Wrong delimiter (tab instead of comma)

    **Solutions:**

    * Re-export fresh CSV from Webflow
    * Use Google Sheets or LibreOffice instead of Excel
    * Check file encoding is UTF-8
  </Accordion>

  <Accordion title="Special characters appear corrupted">
    **Symptoms:** Seeing `é` instead of `é` or similar character issues

    **Cause:** Encoding mismatch (file isn't UTF-8)

    **Solutions:**

    * Re-export from Webflow (should be UTF-8)
    * Convert file to UTF-8 in text editor
    * Check Webflow source data isn't already corrupted
  </Accordion>

  <Accordion title="'Collection ID' or 'Item ID' missing">
    **Symptoms:** Error about missing required Webflow columns

    **Cause:** CSV was edited and system columns were deleted

    **Solution:**

    * Re-export CSV from Webflow without modifications
    * Never delete `Collection ID`, `Item ID`, or `Locale ID` columns
  </Accordion>
</AccordionGroup>

## Field Mapping Issues

<AccordionGroup>
  <Accordion title="Field type mismatch error">
    **Symptoms:** "Cannot convert value to \[type]" error

    **Example:** Trying to map text like "abc" to a `number` field

    **Solutions:**

    * Choose correct field type for your data
    * Clean invalid data in CSV before upload
    * Use `string` type if data is mixed (then convert in Sanity later)
  </Accordion>

  <Accordion title="Required field has empty values">
    **Symptoms:** "Required field \[name] missing in X rows"

    **Cause:** Some CSV rows don't have data for a required field

    **Solutions:**

    * Uncheck "Required" for that field
    * Fill missing values in CSV before upload
    * Accept that rows with missing data will fail to import
  </Accordion>

  <Accordion title="Auto-mapping suggestions are wrong">
    **Symptoms:** MigrateKit suggests wrong field types

    **Cause:** Column names or data patterns are ambiguous

    **Solution:** Manually adjust mappings—suggestions are just starting points, not requirements
  </Accordion>

  <Accordion title="Can't map reference fields">
    **Current limitation:** Reference/relationship fields not supported in MVP

    **Workaround:**

    * Map as `string` to preserve the ID or slug
    * Manually recreate relationships in Sanity Studio after import
    * See [Limitations](/reference/limitations) for details
  </Accordion>
</AccordionGroup>

## Connection Issues

<AccordionGroup>
  <Accordion title="'Invalid API token' error">
    **Symptoms:** Connection test fails with authentication error

    **Causes:**

    * Token was copied with extra spaces or characters
    * Token doesn't have Editor permissions
    * Token was revoked or deleted

    **Solutions:**

    * Create new token with **Editor** permissions
    * Copy token carefully without spaces
    * Verify in Sanity management console that token exists
  </Accordion>

  <Accordion title="'Project not found' error">
    **Symptoms:** Can't connect to Sanity project

    **Causes:**

    * Project ID is incorrect
    * Typo in Project ID
    * Using project name instead of ID

    **Solutions:**

    * Double-check Project ID in Sanity dashboard
    * Copy-paste ID instead of typing
    * Project ID is alphanumeric (e.g., `abc123xyz`), not the project name
  </Accordion>

  <Accordion title="'Dataset not found' error">
    **Symptoms:** Dataset doesn't exist

    **Causes:**

    * Dataset name misspelled
    * Dataset doesn't exist in this project
    * Wrong capitalization

    **Solutions:**

    * Verify dataset name in Sanity project settings (case-sensitive)
    * Create dataset in Sanity if it doesn't exist
    * Common names: `production`, `development`, `staging`
  </Accordion>

  <Accordion title="'Insufficient permissions' error">
    **Symptoms:** Can connect but can't import

    **Cause:** API token has Viewer permissions instead of Editor

    **Solution:**

    * Create new token with **Editor** role
    * Delete old token
    * Update token in MigrateKit
  </Accordion>
</AccordionGroup>

## HTML Conversion Errors

<AccordionGroup>
  <Accordion title="Portable Text looks wrong">
    **Symptoms:** Formatting doesn't match Webflow original

    **Common causes:**

    * Complex HTML structures MigrateKit couldn't convert
    * Nested formatting beyond Portable Text capabilities
    * Custom Webflow elements

    **Solutions:**

    * Review in Sanity Studio and manually fix formatting
    * Simplify complex HTML in Webflow before export
    * Check [HTML Conversion](/concepts/html-conversion) for supported tags
  </Accordion>

  <Accordion title="Line breaks disappeared">
    **Symptoms:** Paragraphs run together

    **Causes:**

    * Multiple `<br>` tags converted incorrectly
    * Empty `<p>` tags were stripped

    **Solution:** Manually add paragraph breaks in Sanity Studio where needed
  </Accordion>

  <Accordion title="Images missing from rich text">
    **Symptoms:** Images that were in Webflow content don't appear

    **Causes:**

    * Image URLs in HTML were invalid
    * Images failed to download
    * Asset upload quota exceeded

    **Solutions:**

    * Check import report for asset failures
    * Verify original URLs in CSV are complete
    * Manually upload missing images in Sanity
  </Accordion>

  <Accordion title="Webflow embeds became code blocks">
    **Expected behavior:** Scripts and iframes are preserved as code blocks for security

    **What to do:**

    * Review code blocks in Sanity Studio
    * Replace with Sanity-compatible alternatives:
      * YouTube embeds → Sanity YouTube plugin
      * Custom scripts → Sanity-safe implementations
    * See [HTML Conversion](/concepts/html-conversion#unsupported-content)
  </Accordion>
</AccordionGroup>

## Import Errors

<AccordionGroup>
  <Accordion title="Some documents failed to import">
    **Symptoms:** Import completes but some rows show errors

    **Common causes:**

    * Required fields with missing values
    * Data type validation failures
    * Invalid Portable Text from malformed HTML

    **Solutions:**

    * Review error messages for specific rows
    * Fix issues in CSV
    * Re-upload and import just the failed rows
  </Accordion>

  <Accordion title="Import is very slow">
    **Symptoms:** Import takes much longer than estimated

    **Causes:**

    * Large number of high-resolution images
    * Many documents (>500)
    * Complex Portable Text requiring heavy processing

    **Solutions:**

    * Be patient—large imports take time
    * Split into smaller batches
    * Optimize/resize images before import
  </Accordion>

  <Accordion title="Assets failed to upload">
    **Symptoms:** Documents import but images are missing

    **Causes:**

    * Invalid image URLs in CSV
    * Network timeouts
    * Sanity asset quota exceeded
    * Images too large

    **Solutions:**

    * Check import report for specific failures
    * Verify URLs are accessible
    * Check Sanity asset quota limits
    * Manually upload failed assets
  </Accordion>

  <Accordion title="'Duplicate ID' error">
    **Symptoms:** Import fails with duplicate document ID error

    **Cause:** Trying to import same data twice

    **Solution:**

    * Delete existing drafts in Sanity first
    * OR MigrateKit will update existing documents (using `Item ID`)
  </Accordion>
</AccordionGroup>

## Data Quality Issues

<AccordionGroup>
  <Accordion title="Dates are wrong">
    **Symptoms:** Dates appear incorrect in Sanity

    **Causes:**

    * Excel auto-formatted dates in CSV
    * Timezone conversion issues
    * Invalid date format

    **Solutions:**

    * Don't open CSV in Excel (use Google Sheets)
    * Verify dates in text editor before upload
    * Check original Webflow data for accuracy
  </Accordion>

  <Accordion title="Links are broken">
    **Symptoms:** Links don't work or point to wrong URLs

    **Causes:**

    * Relative Webflow URLs don't work in new context
    * Links to Webflow-specific pages

    **Solutions:**

    * Update links in Sanity Studio to absolute URLs
    * Review all links after migration
    * Convert Webflow internal links to new site structure
  </Accordion>

  <Accordion title="Boolean fields show 'true'/'false' text">
    **Symptoms:** Boolean field shows text instead of checkbox

    **Cause:** Field mapped as `string` instead of `boolean`

    **Solutions:**

    * Re-map field as `boolean` type
    * MigrateKit converts "true"/"false"/"yes"/"no" automatically
  </Accordion>

  <Accordion title="Numbers have wrong decimals">
    **Symptoms:** `100.50` became `100.5` or similar

    **Cause:** Number precision issue

    **Solution:** This is expected—trailing zeros are mathematically irrelevant. If you need to preserve exact formatting (like prices), use `string` type and format in your frontend.
  </Accordion>
</AccordionGroup>

## Need More Help?

If your issue isn't listed here:

<CardGroup>
  <Card title="Check Prerequisites" icon="list-check" href="/prerequisites">
    Ensure you have everything set up correctly
  </Card>

  <Card title="Review Migration Guide" icon="map" href="/migration/overview">
    Step-by-step instructions for the entire process
  </Card>

  <Card title="Limitations Reference" icon="info-circle" href="/reference/limitations">
    Current features and known limitations
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:support@contentwrap.io">
    Email [support@contentwrap.io](mailto:support@contentwrap.io)
  </Card>
</CardGroup>