Now that we've talked about arrays, we can jump into Portable Text and Block Content.
Portable Text is a specification for block content that allows us to structure and detail our content however we want. You know how Google Docs or Microsoft Word lets you create documents filled with images, tables, text, etc.? Think of Portable Text like that - a rich text editor that allows us to add additional data structures to it.
We won't go into the GROQ or actual structuring of data yet, but we can diagram it out so you can understand it better.
Understanding Portable Text
If we look at a large heading, how would that look in Portable Text? Well, we know a large heading is bolded and large. When you create a H1 in Portable Text, here's what that actually looks like:
As you can see, there's the text of our heading, as well as the style. There's only one piece of text, so we only have one child.
What if we want some rich text? How would that look, with bolding, underlining, and multiple pieces of text?
We have multiple children this time, to distinguish different pieces of text from each other. They all are under this block of a normal style, as well. The marks fields are used to provide further styling for these text children.
For example, the "This part is bolded" has a strong mark, to show that its bolded. The same goes for the "this part is underlined", where we have an underline mark.
What about an Image? How does that look?
It looks basically the same way it would if we called for this schema type in GROQ - this is because of how references work, and Sanity expects you to use their URL generation tool on your website/app/whatever to get the image URL and metadata.
Putting it all together
So how does this look put together?
All that data (and more that I didn't put in this graphic), just for that much? Doesn't seem that worth it... But it is - with Sanity's low latency in Execution and End-to-end times, we can pull and process this amount of data very fast.
Don't believe me? This entire page you've been reading and every page on this site has been written in Portable Text.
Adding Block Content to our Blog Post
Enough talking, let's add a Portable Text Editor to our Blog Post document and start writing.
...,{ name: 'content', type: 'array', title: 'Content', group: 'content', of: [ { type: 'block', }, ],},...,Wait, it's an array? Yup! As you saw in the prior diagram, each batch of content is a block, and to have multiple blocks, we need an array. If you go to Studio now, you'll see the Portable Text Editor:
By default, it has a ton of different options for rich text:
- Headings 1 through 6 (Block Styles)
- Normal and Blockquote Text (Block Styles)
- Bold, Italics, Underlining, Code, and Strikethrough (Inline Styles)
- Ordered and Unordered Lists
- Links
Block Styles apply to blocks of content - such as a heading or normal text. They apply to the whole piece of text. Inline Styles apply to parts and pieces of text within blocks.
Have fun with it - you can really customize this to your heart's content.
Adding image support to the editor
If you haven't noticed, Images aren't supported by default in the Portable Text Editor. This is because we currently have an array of type block, but images are type image, not type block. Luckily, it's really easy to add image support:
...,{ name: 'content', type: 'array', title: 'Content', group: 'content', of: [ { type: 'block', }, { type: 'image', }, ],},...,Yup - that easy. But this brings up a question: can we have an array of multiple types?
Yes!
In Sanity, we can have what are known as heterogenous arrays, or arrays of various types. In fact, this is mainly a Javascript thing, where we can create arrays of whatever elements or objects we want.*
*as long as we ensure that we handle all the fields and elements properly. If we don't in Javascript, we're bound to have errors when dealing with these elements. Luckily for us, Sanity handles this end for us.
If we go back to our Studio, you'll see that we can now add images to our Portable Text:
We can do so much more with Portable Text - any object or schema type can be added into the array we have made. You can do anything you want with it, from adding blocks of code to audio recordings.
The biggest strength of using Portable Text over other rich-text formats such as Markdown is the flexibility and extendibility. You can always add more or less, whatever you need. You're also not confined to how you want to use Portable Text.