Portable Text Conversion

From the author

Convert HTML and Markdown content into Portable Text blocks for Sanity. Use when migrating content from legacy CMSs, importing HTML or Markdown into Sanity, building content pipelines that ingest external content, converting rich text between formats, or programmatically creating Portable Text documents. Covers @portabletext/markdown (markdownToPortableText), @portabletext/block-tools (htmlToBlocks), custom deserializers, and the Portable Text specification for manual block construction.

— the description by sanity

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides methods and specifications for transforming external content formats like HTML and Markdown into the Portable Text format used by Sanity. It covers the use of specific libraries for automated conversion, as well as the structural requirements for manually constructing Portable Text blocks, ensuring developers can programmatically ingest or migrate content into their Sanity projects.

What it does

Converts Markdown to Portable Text using the markdownToPortableText function.
Parses HTML into Portable Text blocks using the htmlToBlocks utility.
Provides the structural specification for manual Portable Text block construction.
Explains the use of _key, _type, and markDefs within the Portable Text schema.
Details how to handle lists and nested content structures.

When to use it

When migrating content from a legacy CMS to Sanity.
When building automated pipelines to ingest HTML or Markdown into a Sanity dataset.
When programmatically generating rich text content from external APIs or databases.
When you need to ensure custom content structures adhere to the Portable Text specification.

Advantages

Standardizes content ingestion across different source formats.
Provides clear paths for both automated and manual content conversion.
Ensures compatibility with Sanity's internal data requirements.
Reduces manual effort during large-scale content migrations.

Usage examples

“How do I convert a Markdown string to Portable Text?”: The agent provides the implementation steps using the markdownToPortableText function from the @portabletext/markdown library.
“What is the structure of a Portable Text block?”: The agent returns the JSON schema for a block, including required fields like _type, _key, and the children array.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/sanity-io/portable-text-conversion/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip portable-text-conversion.zip -d .agents/skills

Documentation by sanity

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"}
  }
]

Key rules:

Every block and span needs _key (unique within the array)
_type: "block" is for text blocks; custom types use their own _type
markDefs holds annotation data; marks on spans reference markDefs[*]._key or are decorator strings
Lists use listItem ("bullet" | "number") and level (1, 2, 3...) on regular blocks

Conversion Rules

Read the rule file matching your source format:

Markdown → Portable Text: rules/markdown-to-pt.md — @portabletext/markdown with markdownToPortableText (recommended)
HTML → Portable Text: rules/html-to-pt.md — @portabletext/block-tools with htmlToBlocks
Manual PT Construction: rules/manual-construction.md — build blocks programmatically from any source

Note: @sanity/block-tools is the legacy package name. Always use @portabletext/block-tools for new projects. The API is the same.

Files

ATTRIBUTION.mdAdded by AutoGineer925 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md2.6 KiB
rules/html-to-pt.md6.9 KiB
rules/manual-construction.md4.9 KiB
rules/markdown-to-pt.md5.5 KiB

LICENSE

MIT License

Copyright (c) 2025 Sanity

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Implement Spec
Matt Pocock· Community
A workflow for implementing technical specifications and tickets using concurrent subagents.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
MCP Builder
AnthropicOfficial
A comprehensive guide for building high-quality Model Context Protocol (MCP) servers to integrate external services with LLMs.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0Low riskHas scriptsGitHub stars of the source repository188.6k
Schema
Corey Haines· Community
Expert guidance for implementing and optimizing JSON-LD schema markup to improve search engine content understanding.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository59k
Postgresql Table Design
Seth Hobson· Community
A comprehensive guide for designing, reviewing, and optimizing PostgreSQL database schemas.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k
SQL Optimization Patterns
Seth Hobson· Community
A comprehensive guide to optimizing SQL database performance through indexing, query plan analysis, and efficient coding patterns.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k
API Scaffolding Fastapi Pro
Seth Hobson· Community
An expert FastAPI developer focused on high-performance, async-first API architecture and production-ready microservices.
Software developmentClaude Code
MITGitHub stars of the source repository42.3k