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

• 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:

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

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:

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

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:

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

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:

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

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:

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:

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.

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