Index of every page on this site: llms.txt
All skills
robotostudio avatar

/portable-text-serialization

@c0b29e4
Run it yourself

Render and serialize Portable Text to React, Svelte, Vue, Astro, HTML, Markdown, and plain text. Use when implementing Portable Text rendering in any frontend framework, building custom serializers for non-standard block types, converting Portable Text to HTML strings server-side, converting Portable Text to Markdown, extracting plain text from Portable Text, or troubleshooting rendering issues with marks, blocks, lists, or custom types.

  • 8 files
  • 24.4 KB
  • MIT
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/robotostudio/turbo-start-sanity/portable-text-serialization

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈118 tokens for metadata: the name and description. ≈961 when used: this file. ≈5.2k more on demand in 7 files.

Description uses 5.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈471 characters, or 5.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

Key Renders Props/Data
types Custom block/inline types (image, code, CTA) value (the block data)
marks Decorators + annotations children + value (mark data)
block Block styles (h1, normal, blockquote) children
list List wrappers (ul, ol) children
listItem List items children
hardBreak Line 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:

Target Package
React Native @portabletext/react-native-portabletext
React PDF @portabletext/react-pdf-portabletext
Solid solid-portabletext
Qwik portabletext-qwik
Shopify Liquid portable-text-to-liquid
PHP sanity-php (SanityBlockContent class)
Python portabletext-html
C# / .NET dotnet-portable-text
Dart / Flutter flutter_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:

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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at c0b29e4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago
metadata
{
  "author": "sanity",
  "version": "1.0.0"
}

README badge

README badge for robotostudio/turbo-start-sanity/portable-text-serialization