Portable Text Conversion

If you're migrating content into Sanity or building ingestion pipelines, this handles the conversion work. It covers three approaches: markdownToPortableText from @portabletext/markdown for direct Markdown conversion, htmlToBlocks from @portabletext/block-tools for HTML migration, and manual block construction when you need full control. The guides break down the Portable Text spec (blocks, spans, keys, markDefs) and show concrete conversion patterns for each source format. Handy reference if you've ever stared at a legacy CMS export wondering how to turn it into proper PT blocks without writing a parser from scratch.

skills.sh installs: 2.9K
GitHub stars: 197
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add sanity-io/agent-toolkit --skill portable-text-conversion --agent claude-code

Installs into .claude/skills of the current project.

Files

Portable Text Conversion

Convert external content (HTML, Markdown) into Portable Text for Sanity. Three main approaches:

markdownToPortableText — Convert Markdown directly using @portabletext/markdown (recommended for Markdown)
htmlToBlocks — Parse HTML into PT blocks using @portabletext/block-tools (for HTML migration)
Manual construction — Build PT blocks directly from any source (APIs, databases, etc.)

Portable Text Specification

Understand the target format before converting. PT is an array of blocks:

[
  {
    "_type": "block",
    "_key": "abc123",
    "style": "normal",
    "children": [
      {"_type": "span", "_key": "def456", "text": "Hello ", "marks": []},
      {"_type": "span", "_key": "ghi789", "text": "world", "marks": ["strong"]}
    ],
    "markDefs": []
  },
  {
    "_type": "block",
    "_key": "jkl012",
    "style": "h2",
    "children": [
      {"_type": "span", "_key": "mno345", "text": "A heading", "marks": []}
    ],
    "markDefs": []
  },
  {
    "_type": "image",
    "_key": "pqr678",
    "asset": {"_type": "reference", "_ref": "image-abc-200x200-png"}
  }
]

SKILL.md on GitHub