We're big believers in standardisation, it's all around you, you've seen:
- Design systems
- Design tokens
- Componentised design
- React patterns
So we thought to ourselves: "Why should Structured Content be any different?". That's why we've written a fully opinionated guide for building your regular style of website.
Now you might be asking: "surely the whole point of Structured Content is to give the developer the freedom to build whatever they like". This is true, but the reason we've written this guide is to make the whole process of learning about Sanity CMS more uniform, and easier to understand.
This guide won't fit everybody, but it should hopefully give you an understanding of how to better structure content. If you're just looking for a Sanity V3 primer, there's a great layman's breakdown here
The anatomy of a good document
We've broken down a good document to help with understanding the why's and how of writing a piece of Sanity schema.
export default {
// Get used to camelCase for naming things
name: "exampleDocument",
title: "Example document",
type: "document",
// The fields array is where you define the fields
// of your document type
fields: [
// The reason we always use Title is because
// Sanity defaults to this field when creating previews
{
name: "title",
title: "Title",
type: "string",
},
{
name: "description",
title: "Description",
// A nice thing to do is to create a rough row limit dependent
// on the description. E.g 3 rows for a short description.
// You can also add validation but we're not covering that here
rows: 3,
type: "text",
},
{
name: "image",
title: "Image",
type: "image",
// You can also add hotspots to images.
// Be aware it's a little trickier if you're using Next Image
hotspot: true,
fields: [
// This is to ensure the alt text is filled out
{
name: "alt",
type: "string",
title: "Alt Text",
},
],
},
// We will explain the basics of portable text in the next section
{
name: "portableText",
title: "Portable text",
type: "portableText",
},
],
// This is how we setup the preview for the document type
// When it's a document we almost always use the description
// field as the subtitle
// However, we advise a little different on a page builder
preview: {
select: {
title: "title",
subtitle: "description",
media: "image",
},
prepare({ title, subtitle, media }) {
return {
title: `${title}`,
subtitle: `${subtitle}`,
media,
};
},
},
};
Previews
The most important element of the above content is a preview, that's where your client can actually see the content being populated from the Document pane.
See how much better the data looks on a properly prepared page builder, in comparison to one without any preparation:
Unprepared preview
Prepared preview
The difference is night and day (not just because of light and dark mode), and your future clients will appreciate the effort.
Adding an icon
Something you might have noticed on the prepared preview above, is the little icons to the left of the title and description. Can you see how much clearer it makes it - providing a client with not just a descriptive text of what it is, but also an image to represent.
import {FaNewspaper} from 'react-icons/fa'
export const SingleArticle = {
title: 'Article',
name: 'article',
type: 'document',
// This icon makes all the difference
icon: FaNewspaper,
fields: [
...
]Page builders
The faster you get used to adding these little icons and nice little previews, the quicker it becomes to scale your structured content. As a nice little bonus, all these icons get pulled through in arrays and other structures to make it even easier to build a page builder and actually know what you're adding to a page.
