SKILL.md
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"}
}
]Key rules:
- Every block and span needs
_key(unique within the array)
_type: "block"is for text blocks; custom types use their own_type
markDefsholds annotation data;markson spans referencemarkDefs[*]._keyor are decorator strings
- Lists use
listItem("bullet" | "number") andlevel(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/markdownwithmarkdownToPortableText(recommended)
- HTML → Portable Text:
rules/html-to-pt.md—@portabletext/block-toolswithhtmlToBlocks
- 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.