Why Portable Text is awesome and you totally want it in your CMS

Let us get this out of the way first: We love HTML. We love Markdown. We use both every day for writing on the web. Even this text began its life in Markdown. And with this rather uncontroversial opening, you can probably see what's coming. We'll argue why you don't want Markdown or HTML stored in your CMS (except as code examples).

Almost everyone does it though, even the new kids on the block. We went through all the vendors on headlesscms.org and browsed through the documentation, and also signed up for those who didn't mention it: with two exceptions they all stored rich text either as HTML or Markdown. Fine if all you do is use Jekyll to render a website, or if you enjoy using dangerouslySetInnerHTML in React.

But if you want to reuse your content in interfaces that aren't on the web. Or if you want more control and functionality in your rich text editor. Or you just want it to be easier to render your rich text in one of the popular frontend frameworks and have your components take care of different parts of your rich text content — you'll either have to find a smart way to parse that Markdown or HTML into what you need, or, more conveniently, just have it stored more sensibly in the first place.

This is why Sanity adopted and developed the Portable Text model for how we store rich text. And now other CMS vendors have started experimenting with it. We're glad it's catching on. Text that is portable is good for everyone.

What does Portable Text actually look like?

Let's get down to business. How does "That was bold of you. Amazing, actually" look in Portable Text?

{
  "myRichTextExample": [{
    "style": "normal",
    "_type": "block",
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "text": "That was ",
        "marks": []
      },
      {
        "_type": "span",
        "text": "bold",
        "marks": [
          "strong"
        ]
      },
      {
        "_type": "span",
        "text": " of you.",
        "marks": []
      }
    ]
  },
  {
    "style": "normal",
    "_type": "block",
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "text": "Amazing, actually.",
        "marks": []
      }
    ]
  }]
}

"Are you out of your mind?" you might say. How is this array of complex objects better than a simple That was **bold** of you. Amazing, actually?

Portable Text isn't meant for humans to read — it's meant for your software to process. If you read it slowly, you can get a feel for what this structure allows you to do. Properties like style, markDefs, and marks let us describe text blocks and inline text in any way we want, for any context we want.

This block of JSON can be serialized into clean text, HTML, or even Markdown. Or if you're writing for voice interfaces, you could easily make an editor for Speech Synthesis Markup Language (SSML).

The real power: marks and annotations

The real power comes with what you can do with markDefs and marks. A straightforward example is links:

{
  "_type":"block",
  "style":"normal",
  "children":[
    {
      "_type":"span",
      "marks":[],
      "text":"This is a "
    },
    {
      "_type":"span",
      "marks":["960611c03ea0"],
      "text":"link"
    }
  ],
  "markDefs":[
    {
      "_key":"960611c03ea0",
      "_type":"link",
      "href":"https://sanity.io"
    }
  ]
}

But what if you wanted to print this and have that link also be a footnote? Portable Text handles that too:

{
  "_type":"block",
  "style":"normal",
  "children":[
    {
      "_type":"span",
      "marks":[],
      "text":"This is a "
    },
    {
      "_type":"span",
      "marks":["960611c03ea0", "4320d93raf12"],
      "text":"link"
    }
  ],
  "markDefs":[
    {
      "_key":"960611c03ea0",
      "_type":"link",
      "href":"https://sanity.io"
    },
    {
      "_key":"4320d93raf12",
      "_type":"footnote",
      "children":[
        {
          "_type":"block",
          "style":"normal",
          "children":[
            {
              "_type":"span",
              "marks":[],
              "text":"This is a "
            },
            {
              "_type":"span",
              "marks":["54234ad981"],
              "text":"link"
            },
            {
              "_type":"span",
              "marks":[],
              "text":" in a footnote!"
            }
          ],
          "markDefs":[
            {
              "_key":"54234ad981",
              "_type":"link",
              "href":"https://sanity.io"
            }
          ]
        }
      ]
    }
  ]
}

If you step back and look at this object as a whole, you'll see that the rich text pattern is recurring inside the mark for the footnote. It's Portable Text all the way down. This approach opens up a lot of possibilities for how and where you want to use your text content.

Want to A/B-test on a product term? Add a mark for the term variation. Want to write unit tests for components with user-generated rich text data? It's much easier with this pattern compared to parsing HTML, which can come with all kinds of surprises and invalid syntax. Want to build a custom editorial comment system that only makes sense in your organization? Portable Text lets you do that without having to invent new markup inside an existing markup language.

Portable Text and AI agents

There's a more recent reason to care about Portable Text: AI agents need structure too.

When an AI agent reads or writes content, unstructured HTML or Markdown is genuinely harder to reason about. Portable Text's JSON structure gives agents something they can work with precisely — the semantic intent of each block is explicit, not implied by markup conventions. That makes it easier to extract meaning, generate context, and write content that fits predictably into your existing schema.

Sanity's Agent API and Agent Context are built on this foundation. Structured content isn't just good for your frontend — it's good infrastructure for agents that need to read and modify your content reliably.

Portable Text in Sanity Studio

Portable Text is also a significant part of how Sanity can offer real-time collaborative editing that works like Google Docs. It also gives you a way to customize how text you paste from other sources — like a webpage or a Word document — should be structured. Perhaps you want to store code snippets in a custom code block, or have your links output as footnotes because you use Sanity to make books.

The Portable Text Editor (PTE) in Sanity Studio is fully customizable. You can add custom block types, inline blocks, annotations, and validation rules that enforce things like heading order, prohibited characters, or your organization's specific style guide.

Rendering Portable Text

Adopting Portable Text for your CMS isn't giving up on HTML. It's accepting that you should be able to structure your content in a way that makes sense for your editors and organizational reality — not by the many specifications that come with markup languages. Then you serialize it into whatever output you need.

The @portabletext/react package makes this straightforward:

import { PortableText } from '@portabletext/react'

<PortableText
  value={portableTextContent}
  components={{ /* custom render components for your block types */ }}
/>

Libraries are available for React, HTML, and other targets. The spec itself lives at portabletext.org.

If you want to go deeper — data structure, serializers, custom blocks, and validation strategies — check out the beginner's guide to Portable Text in the docs.

Join us in the Sanity community on Discord or subscribe to our newsletter.