portable-text-serialization

portable-text-serialization is a skill from the Sanity agent toolkit for rendering and serializing Portable Text — Sanity's JSON-based rich-text format — across many output targets: React, Svelte, Vue, Astro, HTML, Markdown, and plain text. It solves the recurring frontend problem of correctly turning Portable Text blocks, spans, marks, lists, and custom types into rendered output, which trips developers up because renderers only handle standard blocks by default and custom types silently fail to render without explicit component mappings.

The skill explains the Portable Text data structure (an array of blocks with _type, style, children spans, markDefs, listItem, and level, plus decorator and annotation marks) and the shared component-mapping pattern common to the @portabletext/* library family: a components object keyed by types, marks, block, list, listItem, and hardBreak. It routes to framework-specific rule files for React/Next.js, Svelte, Vue, Astro, HTML (server-side), Markdown, and plain-text extraction, each naming the appropriate package such as @portabletext/react, astro-portabletext, or @portabletext/to-html, and lists additional community serializers for React Native, PDF, Solid, Qwik, Shopify Liquid, PHP, Python, .NET, and Flutter. It also documents cross-framework best practices: giving custom types explicit components, keeping the components object stable (defined outside render or memoized) to avoid re-renders, handling missing components with onMissingComponent, and expanding references in GROQ queries so images and internal links resolve.

It targets frontend and full-stack developers building Sanity-backed sites who need to render Portable Text in a specific framework, build custom serializers for non-standard blocks, or convert content to HTML, Markdown, or plain text. It is educational reference documentation with example rendering code and no risky behavior.