How Portable Text is structured
A Portable Text field is an array of blocks, and each block holds an array of child spans of text. The same array can carry custom objects such as an image, a code block or an embed, as long as each one has a _type key. Inside a Sanity document, every array member also needs a _key value, and the Studio editor adds it automatically.
Inline formatting uses marks of two kinds: decorators, stored as plain strings, and annotations, which point to a data object. A link URL lives in the block's markDefs array, and spans reference it by its _key. Lists have no wrapper element. A block becomes a list item through two properties: listItem (for example bullet or number) and level.
Portable Text is written to be parsed by software, and its _type keys make it queryable with GROQ and other JSON tools. The full data model is in the Portable Text specification on GitHub.
Editing and rendering Portable Text
Schema. The
blocktype turns a field into a Portable Text editor, and it has to sit inside anarrayfield.Defaults. Editors get Normal, Heading 1 to 6 and Quote block styles. The default decorators are Strong, Italic, Code, Underline and Strike, and the default annotation is a single link with an
hreffield.Custom sets. Declaring styles, lists, decorators or annotations in the schema replaces the whole default set.
Editor. The Portable Text Editor that Studio inserts for block arrays is open source and can also run as a standalone editor. Its Markdown-style shortcuts, such as a hash for headings or double asterisks for bold, can be switched off per field or globally.
Rendering.
@portabletext/reactrenders blocks with default HTML components that you override or extend through acomponentsobject. It also exportstoPlainText()for meta descriptions or slugs.
For the CMS behind the format, read what Sanity is and how it works. Teams moving rich text out of WordPress can follow the WordPress to Sanity migration guide.
A Portable Text pattern Pagepro uses
The Portable Text editor has no native font-size control, so editors often pick a bigger heading to get bigger text. In its Sanity development work, Pagepro gives editors two separate controls: a semantic tag select (H2, H3, H4 or body text) for the block style, and a size decorator limited to the sizes the design already uses. Editors keep control of text size, and the heading outline stays correct.
Sources
- Block contentSanity · sanity.io
- Specification for Portable TextSanity · github.com
- Configure the Portable Text EditorSanity · sanity.io
- Block (schema type)Sanity · sanity.io
- @portabletext/reactSanity · github.com