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_typemarkDefsholds 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-toolsis the legacy package name. Always use@portabletext/block-toolsfor new projects. The API is the same.
