AutoGineer
Generated banner for Portable Text Conversion
Generated logo for Portable Text Conversion

Portable Text Conversion

SanityOfficialCreated by sanity

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found
Download ZIP

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

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/sanity-io/portable-text-conversion/download

  2. 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

Portable Text Conversion

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

  1. markdownToPortableText — Convert Markdown directly using @portabletext/markdown (recommended for Markdown)

  2. htmlToBlocks — Parse HTML into PT blocks using @portabletext/block-tools (for HTML migration)

  3. 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.md

Attribution

This folder is an unmodified copy of the Agent Skill "portable-text-conversion", distributed by AutoGineer (https://autogineer.com/agent-skills).

The skill's own files are unmodified copies. AutoGineer is not affiliated with or endorsed by the author or the publisher.

Files added by AutoGineer

  • ATTRIBUTION.md: this file, written by AutoGineer

  • LICENSE: copied from LICENSE

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.

Attribution and licence

Created by
sanity
Publisher
Sanity (Official)
Source
sanity-io/agent-toolkit · skills/portable-text-conversion · commit 3ed3a14
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by sanity.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download portable-text-conversion.zip