sanity-io/agent-toolkit

portable-text-serialization

Render and serialize Portable Text to React, Svelte, Vue, Astro, HTML, Markdown, and plain text.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/sanity-io/agent-toolkit --skill portable-text-serialization

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Portable Text Serialization

Render Portable Text content across frameworks using the @portabletext/* library family. Each library follows the same component-mapping pattern: you provide a components object that maps PT node types to framework-specific renderers.

Portable Text Structure (Quick Reference)

PT is an array of blocks. Each block has _type, optional style, children (spans), markDefs, listItem, and level.

Root array
├── block (_type: "block")
│   ├── style: "normal" | "h1" | "h2" | "blockquote" | ...
│   ├── children: [span, span, ...]
│   │   └── span: { _type: "span", text: "...", marks: ["strong", "<markDefKey>"] }
│   ├── markDefs: [{ _key, _type: "link", href: "..." }, ...]
│   ├── listItem: "bullet" | "number" (optional)
│   └── level: 1, 2, 3... (optional, for nested lists)
├── custom block (_type: "image" | "code" | any custom type)
└── ...more blocks

Marks come in two forms:

  • Decorators: string values in marks[] like "strong", "em", "underline", "code"
  • Annotations: keys in marks[] referencing entries in markDefs[] (e.g., links, internal references)

Component Mapping Pattern (All Frameworks)

Every @portabletext/* library accepts a components object with these keys:

KeyRendersProps/Data
typesCustom block/inline types (image, code, CTA)value (the block data)
marksDecorators + annotationschildren + value (mark data)
blockBlock styles (h1, normal, blockquote)children
listList wrappers (ul, ol)children
listItemList itemschildren
hardBreakLine breaks within a block—

Framework-Specific Rules

Read the rule file matching your framework:

  • React / Next.js: rules/react.md — @portabletext/react or next-sanity
  • Svelte / SvelteKit: rules/svelte.md — @portabletext/svelte
  • Vue / Nuxt: rules/vue.md — @portabletext/vue
  • Astro: rules/astro.md — astro-portabletext
  • HTML (server-side): rules/html.md — @portabletext/to-html
  • Markdown: rules/markdown.md — @portabletext/markdown
  • Plain text extraction: rules/plain-text.md — @portabletext/toolkit

Additional Community Serializers

These are listed on portabletext.org but don't have dedicated rule files:

TargetPackage
React Native@portabletext/react-native-portabletext
React PDF@portabletext/react-pdf-portabletext
Solidsolid-portabletext
Qwikportabletext-qwik
Shopify Liquidportable-text-to-liquid
PHPsanity-php (SanityBlockContent class)
Pythonportabletext-html
C# / .NETdotnet-portable-text
Dart / Flutterflutter_sanity_portable_text

Common Patterns (All Frameworks)

Custom Types Need Explicit Components

PT renderers only handle standard blocks by default. Custom types (image, code, callToAction, etc.) require explicit component mappings — they won't render otherwise.

Keep Components Object Stable

In React/Vue, define components outside the render function or memoize it. Recreating on every render causes unnecessary re-renders.

Handle Missing Components Gracefully

All libraries accept onMissingComponent to control behavior when encountering unknown types:

  • false — suppress warnings
  • Custom function — log or report

Querying PT with GROQ

Always expand references inside custom blocks:

groq
body[]{
  ...,
  _type == "image" => {
    ...,
    asset->
  },
  markDefs[]{
    ...,
    _type == "internalLink" => {
      ...,
      "slug": @.reference->slug.current
    }
  }
}

Related by task

from this repository

More skills

All skills
sanity-io
Official

sanity-best-practices

Sanity development best practices for schema design, GROQ queries, TypeGen, Visual Editing, images, Portable Text, Studio structure, localization, migrations, Sanity Functions, webhooks, Blueprints, and framework integrations such as Next.js, Nuxt, Astro, Remix, SvelteKit, Angular, Hydrogen, the App SDK, and Studios or apps running in the Sanity Dashboard (defineApplication). Use this skill whenever working with Sanity schemas, defineType or defineField, GROQ or defineQuery, content modeling, Pr

1h installs
3
GitHub stars
201
Updated
Nov 19
sanity-io
Official

sanity-migration

Plans, implements, and reviews migrations from other CMSes and content systems into Sanity. Use when migrating or replatforming to Sanity from AEM, Adobe Experience Manager, Contentful, Strapi, Webflow, WordPress, Payload, Drupal, Markdown/MDX/frontmatter files, WXR/XML exports, CMS APIs, database dumps, static HTML, or when designing extraction, transformation, Portable Text conversion, asset migration, redirects, validation, and cutover workflows.

1h installs
3
GitHub stars
201
Updated
Nov 19
sanity-io
Official

content-modeling-best-practices

Structured content modeling guidance for schema design, content architecture, content reuse, references versus embedded objects, separation of concerns, and taxonomies across Sanity and other headless CMSes. Use this skill when designing or refactoring content types, deciding field shapes, debating reusable versus nested content, planning omnichannel content models, or reviewing whether a schema is too page-shaped or presentation-driven.

1h installs
2
GitHub stars
197
Updated
Nov 10
sanity-io
Official

sanity-studio-upgrade

Produces a tailored Sanity Studio upgrade plan by inspecting the repository's installed versions, config, and source, then reporting only the breaking changes that actually apply. Covers Studio v3 and later; v2 projects are identified and redirected, not planned. Use this skill whenever someone wants to upgrade, migrate, or modernize a Sanity Studio across one or more major versions from v3 onward, asks what will break if they bump the sanity package, asks why their Studio broke after an upgrade

1h installs
2
GitHub stars
196
Updated
Oct 27