How to Add Superscripts and Subscripts to Sanity CMS: A Step-by-Step Guide

Introduction

Have you ever needed to display scientific formulas like H₂O or E=mc² in your Sanity CMS content? Or perhaps you need to add trademark symbols, footnote references, or mathematical expressions to your website? While Sanity CMS offers powerful content management capabilities, it doesn't include superscript and subscript text decorators out of the box. This limitation can be frustrating when working with technical, scientific, or academic content.

In this comprehensive tutorial, I'll walk you through the process of extending Sanity's block content with custom superscript and subscript decorators. These text formatting options are essential for various content types, from scientific articles and legal disclaimers to academic references and product descriptions.

By the end of this tutorial, you'll be able to:

• Add custom superscript and subscript decorators to your Sanity schema
• Create React components to render these decorators in the Sanity Studio
• Implement the necessary frontend code to display formatted text on your website
• Understand how to extend this approach to other custom text decorators

Prerequisites

Before we dive in, make sure you have:

• A working Sanity CMS project (version 2.0 or later)
• Basic knowledge of Sanity schemas and block content
• Familiarity with React components
• Access to your project's schema files
• Node.js and npm installed on your machine

Solution Overview

Sanity CMS uses a system called Portable Text (formerly Block Content) for rich text editing. This format allows for structured content with marks and decorators that can be serialized to different output formats. By default, Sanity includes basic text decorators like bold, italic, underline, and code, but it's designed to be extensible.

Our solution involves:

1. Extending the block content schema to include superscript and subscript decorators
2. Creating custom React components to render these decorators in the Sanity Studio
3. Implementing custom icons for better visual identification
4. Setting up the frontend serialization to properly render the formatted text

This approach maintains the structured nature of Portable Text while adding the specific formatting options we need. The benefit of this method is that it's non-destructive and follows Sanity's recommended patterns for customization.

Let's get started with the implementation!

Step 1: Understanding Block Content in Sanity

What are Block Content Decorators?

Before adding custom decorators, it's important to understand how Sanity's block content works. In Sanity, rich text is stored as structured data using the Portable Text specification. Text decorators (also called "marks") are applied to spans of text within blocks.

The default block content in Sanity includes decorators like:

// Default decorators in Sanitydecorators: [  { title: 'Strong', value: 'strong' },  { title: 'Emphasis', value: 'em' },  { title: 'Code', value: 'code' },  { title: 'Underline', value: 'underline' },  { title: 'Strike', value: 'strike-through' },]

When a decorator is applied to text, it gets stored in the content's JSON structure like this:

{  "_type": "block",  "children": [    {      "_type": "span",      "text": "This is ",      "marks": []    },    {      "_type": "span",      "text": "bold",      "marks": ["strong"]    },    {      "_type": "span",      "text": " text",      "marks": []    }  ]}

Our goal is to add superscript and subscript as new decorator options, which will be stored similarly in the content structure.

Step 2: Locating Your Schema Files

Finding the Right Schema File

To add custom decorators, we need to modify the schema file that defines your block content. This is typically found in your Sanity project directory structure.

1. Navigate to your Sanity project folder
2. Look for the schemas directory
3. Find the schema file that defines your block content field

The exact location might vary depending on your project structure, but it's commonly found in paths like:

• schemas/blockContent.js
• schemas/objects/blockContent.js
• schemas/schema.js (if you have a simpler project)

If your project has multiple block content definitions, you'll need to modify each one where you want superscript and subscript to be available.

Step 3: Adding Custom Decorators to Your Schema

Modifying the Block Content Schema

Now that you've found your schema file, let's add the superscript and subscript decorators:

// Before: Default block content schemaexport default {  title: 'Block Content',  name: 'blockContent',  type: 'array',  of: [    {      title: 'Block',      type: 'block',      styles: [        { title: 'Normal', value: 'normal' },        { title: 'H1', value: 'h1' },        { title: 'H2', value: 'h2' },        { title: 'H3', value: 'h3' },        { title: 'Quote', value: 'blockquote' },      ],      lists: [{title: 'Bullet', value: 'bullet' }, {title: 'Number', value: 'number' }],      marks: {        decorators: [          { title: 'Strong', value: 'strong' },          { title: 'Emphasis', value: 'em' },          { title: 'Code', value: 'code' },          { title: 'Underline', value: 'underline' },          { title: 'Strike', value: 'strike-through' },        ],        annotations: [          // Annotations like links would be here        ]      }    }  ]}

Now, let's modify it to add our new decorators:

// After: Modified block content schema with superscript and subscriptexport default {  title: 'Block Content',  name: 'blockContent',  type: 'array',  of: [    {      title: 'Block',      type: 'block',      styles: [        { title: 'Normal', value: 'normal' },        { title: 'H1', value: 'h1' },        { title: 'H2', value: 'h2' },        { title: 'H3', value: 'h3' },        { title: 'Quote', value: 'blockquote' },      ],      lists: [{ title: 'Bullet', value: 'bullet' }, {title: 'Number', value: 'number' }],      marks: {        decorators: [          { title: 'Strong', value: 'strong' },          { title: 'Emphasis', value: 'em' },          { title: 'Code', value: 'code' },          { title: 'Underline', value: 'underline' },          { title: 'Strike', value: 'strike-through' },          { title: 'Superscript', value: 'sup' }, // Added superscript          { title: 'Subscript', value: 'sub' },   // Added subscript        ],        annotations: [          // Annotations remain unchanged        ]      }    }  ]}

What we've done here is add two new decorators to the existing list:

• { title: 'Superscript', value: 'sup' } for superscript text
• { title: 'Subscript', value: 'sub' } for subscript text

The value properties ('sup' and 'sub') are important as they'll be used as the mark names in the Portable Text structure and correspond to the HTML tags we'll use for rendering.

Step 4: Rendering Decorated Content on the Frontend

Setting Up Frontend Serialization

Now that we've configured Sanity Studio, we need to ensure that our superscript and subscript formatting renders correctly on the frontend. The approach varies depending on the frontend framework you're using, but here's how to do it with the @portabletext/react library:

First, install the necessary package if you haven't already:

npm install @portabletext/react

Then, create a serializer configuration for your Portable Text content:

// In your frontend code (React example)import { PortableText as SanityPortableText } from '@portabletext/react'// Define custom serializers for our marksconst components = {  marks: {    sup: ({ children }) => <sup>{children}</sup>,    sub: ({ children }) => <sub>{children}</sub>,    // Include other mark serializers as needed  },  // Include other component serializers as needed}// In your component that renders Sanity contentconst PortableText = ({ blockContent }) => {  return (    <div className="content">      <SanityPortableText        value={blockContent}        components={components}      />    </div>  )}

This configuration tells the Portable Text renderer how to handle our custom 'sup' and 'sub' marks, transforming them into the appropriate HTML elements.

If you're using Next.js with Sanity, the setup might look like this:

import { PortableText as SanityPortableText } from '@portabletext/react'import { client } from '../lib/sanity'// Define custom serializersconst components = {  marks: {    sup: ({ children }) => <sup>{children}</sup>,    sub: ({ children }) => <sub>{children}</sub>,  }}// Fetch and render contentexport default function Page({ pageData }) {  return (    <main>      <h1>{pageData.title}</h1>      <div className="content">        <SanityPortableText          value={pageData.content}          components={components}        />      </div>    </main>  )}export async function getStaticProps() {  const pageData = await client.fetch(`    *[_type == "page" && slug.current == "my-page"][0]{      title,      content    }  `)    return {    props: {      pageData    }  }}

Step 5: Testing Your Implementation

Verifying Everything Works

Now it's time to test your implementation to make sure everything is working correctly:

1. Start (or restart) your Sanity Studio.
2. Navigate to a document with a block content field
3. Select some text and look for the new superscript and subscript buttons in the formatting toolbar
4. Apply the formatting and verify it appears correctly in the editor
5. Save the document and deploy your changes if necessary
6. Check your frontend to ensure the formatting renders correctly there as well

Screenshot: Sanity Studio with superscript and subscript decorators in the formatting toolbar

Common Issues and Troubleshooting

Problem: Decorators Not Appearing in the Toolbar

Symptoms: You've added the decorators to your schema, but they don't appear in the formatting toolbar in Sanity Studio.

Solution: Check that you've:

• Correctly modified the right schema file
• Registered the custom components with the block editor
• Restarted the Sanity Studio after making changes
• Deployed the changes to your Sanity Studio if you're using a deployed version

// Double-check your schema configurationmarks: {  decorators: [    // Existing decorators...    { title: 'Superscript', value: 'sup' }, // Make sure these are added    { title: 'Subscript', value: 'sub' },  ]}

Problem: Formatting Doesn't Appear on the Frontend

Symptoms: The decorators work fine in Sanity Studio, but the formatting doesn't show up on your website.

Solution: Verify that:

• You've set up the correct serializers for your frontend
• Your frontend is fetching the latest content from Sanity
• There are no CSS rules overriding the sup and sub styling

Problem: Inconsistent Styling Across Browsers

Symptoms: The superscript and subscript text looks different in various browsers.

Solution: Add consistent CSS styling to normalize the appearance:

/* Add this to your global CSS */sup, sub {  font-size: 75%;  line-height: 0;  position: relative;  vertical-align: baseline;}sup {  top: -0.5em;}sub {  bottom: -0.25em;}

Problem: Editor Performance Issues

Symptoms: The Sanity editor becomes slow after adding custom decorators.

Solution: This is rare but could happen if you have many custom components or complex rendering logic. Simplify your custom components and make sure they're optimized for performance.

Advanced Techniques

Implementing Keyboard Shortcuts

You can enhance the user experience by adding keyboard shortcuts for your new decorators. This is done by modifying your block editor configuration:

const customStyles = {  // Existing configuration...  decorators: [    // Existing decorators...    {      title: 'Superscript',      value: 'sup',      component: SuperscriptDecorator,      icon: SuperscriptIcon,      hotkey: 'mod+shift+.'  // Ctrl/Cmd + Shift + .    },    {      title: 'Subscript',      value: 'sub',      component: SubscriptDecorator,      icon: SubscriptIcon,      hotkey: 'mod+shift+,'  // Ctrl/Cmd + Shift + ,    }  ]}

Real-world Applications

Now that you have superscript and subscript capabilities in your Sanity CMS, here are some practical uses:

Scientific Content

Display chemical formulas correctly:

• Water: H₂O
• Carbon dioxide: CO₂

Mathematical expressions:

• E=mc²
• x² + y² = r²
• Logarithmic notation: log₁₀

Legal and Business Content

Add proper trademark and registered symbols:

• Product^TM
• Brand
• Copyright©

Academic and Reference Content

Create properly formatted citations and footnotes:

• Reference to a source¹
• Additional information²
• Footnote markers³

Product Descriptions

Display measurements and units correctly:

• Screen size: 15.6^"
• Area: 25m²
• Temperature: 20°C

Conclusion

In this tutorial, you've learned how to extend Sanity CMS with custom superscript and subscript text decorators. We've covered:

• Understanding Sanity's block content system
• Adding custom decorators to your schema
• Creating React components for rendering in the editor
• Implementing custom icons for better usability
• Setting up frontend serialization for proper display
• Troubleshooting common issues
• Advanced techniques for further customization

These enhancements will allow your content creators to produce more sophisticated and properly formatted content for scientific, academic, legal, and technical purposes.

Don't Navigate Your Migration Alone

ContentWrap can simplify your CMS migration, with proven strategies on reducing costs, transferring data, and designing studios.

Book a Call

Next Steps

Now that you understand how to add custom decorators, you might want to explore:

• Adding more custom formats like highlighting or small caps
• Creating complex nested decorators
• Building a complete plugin for text formatting
• Implementing advanced serialization options for different frontend frameworks

Resources

For more information, check out these resources:

• Sanity Block Content Documentation
• Portable Text Specification
• @portabletext/react Library
• Sanity Plugin Development Guide