` → New line within block * Multiple `
` → New blocks ### Text Formatting | HTML | Portable Text Mark | Visual | | -------------- | --------------------------- | ----------------- | | `` | `marks: ["strong"]` | **Bold** | | `` | `marks: ["strong"]` | **Bold** | | `` | `marks: ["em"]` | *Italic* | | `` | `marks: ["em"]` | *Italic* | | `` | `marks: ["underline"]` | Underlined | | `
` | `marks: ["code"]` | `Inline code` |
### Lists
**Unordered lists:**
```html theme={null}
- First item
- Second item
```
Becomes:
```json theme={null}
[
{"_type": "block", "listItem": "bullet", "children": [...]},
{"_type": "block", "listItem": "bullet", "children": [...]}
]
```
**Ordered lists:**
```html theme={null}
- First step
- Second step
```
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}
Click here
```
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}
Here's an image: 
```
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}
Red text
```
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}
Content
```
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}
```
Becomes:
```json theme={null}
{
"_type": "code",
"language": "html",
"code": ""
}
```
### Iframes
```html theme={null}
```
Becomes:
```json theme={null}
{
"_type": "code",
"language": "html",
"code": ""
}
```
### Custom Webflow Elements & Unknown Tags
```html theme={null}
Content
```
Becomes:
```json theme={null}
{
"_type": "code",
"language": "html",
"code": "Content "
}
```
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
**HTML:**
```html theme={null}
My Blog Post
This is bold and italic text.
Here's a link.
```
**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": "."}
]
}
]
```
**HTML:**
```html theme={null}
- First item
- Second item with bold
```
**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"]}
]
}
]
```
**HTML:**
```html theme={null}
A paragraph with bold link.
```
**Portable Text:**
```json theme={null}
[
{
"_type": "block",
"children": [
{"text": "A paragraph with "},
{
"text": "bold link",
"marks": ["strong", {"_type": "link", "href": "/link"}]
},
{"text": "."}
]
}
]
```
## Best Practices
### Before Migration
Remove unnecessary HTML before exporting:
* Delete empty `` and `` tags
* Remove inline styles you don't need
* Simplify complex nested structures
Note any Webflow-specific elements that will need replacement:
* Custom interactions
* Dynamic embeds
* Complex grids or layouts
Export a small collection first to see how your HTML converts
### After Migration
Check all code blocks in Sanity Studio:
* Replace scripts with Sanity-safe alternatives
* Convert iframes to proper embeds
* Remove unnecessary preserved HTML
Adjust any conversion quirks:
* Incorrect heading levels
* Lost spacing
* Misinterpreted formatting
Enhance content with Portable Text features:
* Custom block types
* Better link handling
* Responsive embeds
## Common Issues
**Cause:** Multiple `
` tags or `` tags with empty content.
**Fix:** Manually add paragraph breaks in Sanity Studio where needed.
**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.
**Cause:** Images didn't upload (network error, quota exceeded).
**Fix:** Check the import report for asset failures and manually upload missing images.
**Cause:** Relative Webflow links may not work in new context.
**Fix:** Update links in Sanity Studio to point to correct URLs.
**Expected:** MigrateKit preserves unknown HTML as code blocks for safety.
**Fix:** Review code blocks and replace with Sanity-compatible alternatives.