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

SKILL.md