Why Rich Text to Portable Text Conversion Is Critical
Every modern content tool—from Google Docs to WordPress—stores formatted text as HTML behind the scenes. When you make text bold in Google Docs, it wraps it in <strong> tags. When you create a list in Word, it generates <ul> and <li> elements. This HTML-based approach works great for display, but it's a nightmare for structured content management.
The Format Incompatibility Problem
Rich text HTML is designed for presentation:
<p>This is <strong>important</strong> text with a <a href="https://example.com">link</a>. </p><ul> <li>First item</li> <li>Second item</li></ul>
But Sanity's Portable Text is designed for structure and meaning:
[ { "_key": "392a52526d22", "children": [ { "_type": "span", "marks": [], "text": "This is ", "_key": "a09cccbacb52" }, { "_type": "span", "marks": [ "strong", "strong" ], "text": "important", "_key": "8f38468dddf5" }, { "_type": "span", "marks": [], "text": " text with a ", "_key": "fae8e79b8cdd" }, { "_type": "span", "marks": [ "67864de13b4c" ], "text": "link", "_key": "991894ed50fe" }, { "_type": "span", "marks": [], "text": ".", "_key": "4376fbb71f82" } ], "markDefs": [ { "_key": "67864de13b4c", "_type": "link", "href": "https://example.com/" } ], "_type": "block", "style": "normal" }, { "_key": "c5b078980311", "children": [ { "_type": "span", "marks": [], "text": "First item", "_key": "1b35f35ffc30" } ], "markDefs": [], "_type": "block", "style": "normal", "level": 1, "listItem": "bullet" }, { "_key": "d8c21a6deeb3", "children": [ { "_type": "span", "marks": [], "text": "Second item", "_key": "f9597350e7b1" } ], "markDefs": [], "_type": "block", "style": "normal", "level": 1, "listItem": "bullet" }]
Manual conversion requires understanding both formats and painstakingly reconstructing every element.
Who Needs Rich Text to Portable Text Conversion?
Content Migration Teams
Organizations moving from WordPress, Drupal, or traditional CMSes to Sanity face a massive challenge: thousands of articles formatted in rich text editors need conversion to Portable Text. Manual migration costs $50,000+ in labor for large sites.
Real Impact: A media company with 5,000 articles saves 2,500 hours (6 months of work) using automated conversion.
Marketing Teams Using Google Docs
Most marketing teams draft content in Google Docs or Word before publishing. But copying from these tools into Sanity strips all formatting, requiring manual recreation of every bold, italic, link, and list.
Real Impact: Marketing teams waste 5 hours weekly on reformatting—that's 260 hours annually.
Documentation Teams
Technical writers working in Confluence, Notion, or GitBook need to preserve complex formatting—code blocks, nested lists, tables, and callouts—when moving to Sanity.
Real Impact: A documentation team reduced migration time from 2 hours to 5 minutes per article.
Digital Agencies
Agencies managing multiple client migrations need reliable, fast conversion that preserves formatting integrity across different source systems.
Real Impact: Agencies report 80% reduction in migration project timelines.
What Our Rich Text Converter Handles
Complete Formatting Support
- Text Styles - Bold, italic, underline, strikethrough
- Headings - All levels (H1-H6) with proper hierarchy
- Lists - Ordered, unordered, and nested lists
- Links - External, internal, and mailto links
- Blockquotes - Preserved with proper structure
- Code - Inline code and code blocks
Source Compatibility
- Google Docs - Direct paste from docs
- Microsoft Word - Online and desktop versions
- Notion - Rich text blocks
- WordPress - Classic and Gutenberg editors
- Medium - Article content
- Confluence - Wiki pages
- Any WYSIWYG - TinyMCE, CKEditor, Quill, etc.
How Rich Text Conversion Works
Step 1: Parse HTML Structure
The converter analyzes the HTML generated by rich text editors, identifying:
- Block-level elements (paragraphs, headings, lists)
- Inline formatting (bold, italic, links)
- Nested structures (lists within lists)
- Special elements (images, tables, embeds)
Step 2: Build Portable Text Tree
Each HTML element is transformed into its Portable Text equivalent:
<p> → Block with style "normal"<strong> → Span with mark "strong"<a> → Span with link annotation<ul>/<li> → Block with listItem "bullet"
Step 3: Generate Valid JSON
The converter ensures:
- Unique keys for every block and span
- Proper mark definitions
- Valid parent-child relationships
- Correct ordering and nesting
Common Conversion Challenges Solved
Nested Formatting
Problem: Multiple overlapping formats like bold italic links
Solution: Intelligent mark stacking preserves all formatting layers
Mixed List Types
Problem: Numbered lists inside bullet lists break structure
Solution: Recursive parsing maintains proper list hierarchy
Inline Images
Problem: Images embedded in paragraphs need special handling
Solution: Automatic extraction and conversion to image blocks
Custom Styles
Problem: Editor-specific styles don't map to Portable Text
Solution: Smart fallbacks to closest semantic equivalent
Using Your Converted Content
Direct Studio Import
- Copy the generated Portable Text JSON
- In Sanity Studio, open your document
- Click the three-dot menu in the Portable Text field
- Select "Paste Portable Text"
- Paste and save
Advanced Features Coming Soon
Bulk Conversion (Q1 2026)
- Process multiple documents simultaneously
- Maintain document relationships
- Preserve metadata and properties
- Direct API integration
Why Choose ContentWrap's Converter?
Built on Migration Experience
We've migrated millions of words from every major platform to Sanity. Our converter handles edge cases others miss.
Format Preservation
Unlike basic converters that strip formatting, we preserve the intent and structure of your original content.
Developer-Friendly
Generated JSON is properly formatted, validated, and ready for both Studio and API use.
