How to Fix the Numbered List Reset Bug in Sanity CMS: A Step-by-Step Guide

Introduction

Have you ever spent hours crafting the perfect content in Sanity Studio, only to discover that your carefully structured numbered lists are continuing from previous counts instead of resetting to 1? This frustrating bug has been plaguing content editors working with Sanity's Portable Text Editor, creating headaches for both content creators and developers alike.

When you create a new numbered list after paragraphs or headers, you rightfully expect the list to start from 1. However, in affected versions of Sanity, the list stubbornly continues from wherever the previous list left off — turning what should be a "Step 1" into "Step 3" or "Step 8" without your permission.

This issue doesn't just affect how content looks in the editor; it carries through to your published content, creating confusion for readers and requiring extra work for content teams to manually correct the numbering.

Good news: Sanity officially fixed this bug in version 3.53.0 with a note in their release documentation stating they "Fixed an issue that could cause wrong list counts in the Portable Text Editor."

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

• Upgrade your Sanity Studio installation to version 3.53.0 or higher
• Verify that the numbered list bug has been resolved
• Handle any potential complications during the upgrade process
• Implement best practices for maintaining your Sanity installation

Prerequisites

Before we begin, make sure you have:

• An existing Sanity Studio project
• Access to your project's codebase and package management
• Basic knowledge of npm or yarn
• Terminal/command line familiarity
• Administrator privileges for your Sanity project

Understanding the Problem

The numbered list reset bug manifests when content editors create multiple numbered lists separated by other content elements like paragraphs, headings, or images. Instead of each new list starting with "1," the numbering continues from the previous list — creating a frustrating experience for both editors and readers.

What's Happening Behind the Scenes

In Sanity's Portable Text Editor (the rich text editing component), lists are handled as special block elements. When functioning properly, a new list block should reset its counter whenever it's preceded by a non-list block. However, in affected versions, the list counter state persists across blocks, creating this unexpected behavior.

Here's what the problem looks like in practice:

Notice how after the paragraph, the second list starts with 3 instead of 1 — a clear indication that the list counter isn't resetting as it should.

This issue affects the Portable Text's underlying data structure and subsequently impacts how content renders on the frontend. For content teams working on tutorials, step-by-step guides, or any structured content, this bug requires constant manual intervention or complex workarounds.

Solution Overview

The definitive solution to this problem is upgrading to Sanity version 3.53.0 or higher, which contains an official fix for the numbered list bug. This version introduced a correction to how the Portable Text Editor manages list state between blocks, ensuring that new lists properly reset their counters.

Why Upgrading Is the Best Approach

While there are temporary workarounds (which we'll cover later), upgrading provides the most sustainable solution for several reasons:

1. Official Fix: This is an officially supported solution from Sanity, not a hack or workaround
2. Future Compatibility: Ensures compatibility with future Sanity features and updates
3. Editor Experience: Improves the content editing experience without requiring manual intervention
4. Additional Benefits: Includes other bug fixes and performance improvements beyond just the list numbering issue

The upgrade process involves updating your Sanity dependencies in your project's package.json file and running the appropriate package manager commands. In most cases, this is a straightforward process that takes less than an hour to complete.

Step-by-Step Upgrade Process

Let's walk through the process of upgrading your Sanity installation to fix the numbered list bug.

Step 1: Check Your Current Sanity Version

Before making any changes, verify your current Sanity version to understand the scope of the upgrade.

Open your terminal, navigate to your Sanity Studio project directory, and run:

npx sanity --version

Alternatively, you can check the version in your package.json file:

grep "sanity" package.json

Make note of your current version. If you're already on version 3.53.0 or higher, you should already have the fix in place (though you'll still want to verify this).

Step 2: Update Your Dependencies

Now, update the Sanity dependencies in your package.json file. You can do this manually or using npm/yarn commands.

Manual Method (most precise):

Open your package.json file and update all Sanity-related dependencies to at least version 3.53.0:

Before:

{  "dependencies": {    "@sanity/client": "^3.4.1",    "@sanity/image-url": "^1.0.2",    "sanity": "^3.23.4",    "sanity-plugin-media": "^2.0.5",    // Other dependencies...  }}

After:

{  "dependencies": {    "@sanity/client": "^3.4.1",    "@sanity/image-url": "^1.0.2",    "sanity": "^3.53.0",    "sanity-plugin-media": "^2.0.5",    // Other dependencies...  }}

Automated Method:

Alternatively, use npm or yarn to update all Sanity packages:

For npm:

npm update sanity @sanity/client @sanity/image-url

For yarn:

yarn upgrade sanity @sanity/client @sanity/image-url

Ready to Budget for Sanity?

ContentWrap helps companies save thousands on their Sanity bills through smart caching strategies and optimized API usage.

Calculate Your Costs

Step 3: Install Updated Dependencies

After updating your package.json, install the updated dependencies:

For npm:

npm install

For yarn:

yarn install

This may take a few minutes as it downloads and installs the updated packages.

Step 4: Check for Breaking Changes

Consult the Sanity release notes to see if there are any breaking changes between your previous version and 3.53.0 that might affect your project.

If you're making a significant version jump (e.g., from 3.20.x to 3.53.x), you'll want to pay special attention to any major changes that might require updates to your schemas or configuration.

Step 5: Start Your Development Server

Once the installation is complete, start your development server to ensure everything is working correctly:

npm run dev# oryarn dev

If you encounter any errors during startup, consult the error messages for guidance on resolving them. The most common issues relate to plugin compatibility or configuration changes.

Step 6: Deploy the Updated Studio

After verifying that everything works correctly in your development environment, deploy the updated Sanity Studio:

sanity deploy

This will make the updated Studio available to all your content editors.

Verifying the Fix

Now that you've upgraded, let's verify that the numbered list bug is actually fixed.

Test Case: Creating Multiple Numbered Lists

1. Open your upgraded Sanity Studio
2. Create or edit a document with the Portable Text Editor
3. Create a numbered list with a few items
4. Add a paragraph or heading after the list
5. Create another numbered list

If the fix is working correctly, the second list should start with "1" instead of continuing from the previous list:

Test Case: Complex Document Structure

For a more thorough test:

1. Create a document with multiple sections
2. Include several numbered lists separated by different block types (paragraphs, headings, images, etc.)
3. Verify that each list starts with "1"
4. Try editing existing lists to add or remove items
5. Confirm that other lists remain correctly numbered

If all tests pass, congratulations! The numbered list bug has been fixed in your Sanity Studio installation.

Troubleshooting Common Issues

Despite the straightforward upgrade process, you might encounter some issues. Here's how to address the most common problems:

Issue 1: Lists Still Don't Reset After Upgrade

Problem: You've upgraded to Sanity 3.53.0+, but lists still don't reset properly.

Solution:

• Clear your browser cache completely
• Ensure you're actually using the updated Studio (check the version in the Studio's help menu)
• Try in an incognito/private browsing window
• Verify that your deployment was successful

Issue 2: Upgrade Process Fails

Problem: The npm/yarn upgrade command fails with dependency conflicts.

Solution:

# For npmnpm install --force# For yarnyarn install --force

If this doesn't resolve the issue, try removing your node_modules directory and reinstalling:

rm -rf node_modulesnpm install# oryarn install

Issue 3: Studio Won't Start After Upgrade

Problem: After upgrading, your Sanity Studio fails to start with errors.

Solution: Check the error messages carefully. The most common issues are:

• Plugin compatibility: Update any Sanity plugins to versions compatible with 3.53.0+
• Configuration changes: Some configuration options may have changed in newer versions

If you can't resolve the errors, consider a gradual upgrade approach by updating to intermediate versions first.

Issue 4: Previous Content Displays Incorrectly

Problem: After the upgrade, previously created content displays incorrectly.

Solution: This is rare but can happen if the underlying data structure has changed. You may need to:

1. Export your content
2. Fix any structural issues in the exported data
3. Re-import the corrected data

Contact Sanity support if you encounter persistent issues with existing content.

Issue 5: Custom Components Break After Upgrade

Problem: Custom Portable Text components no longer work correctly.

Solution: Review any custom components against the latest Sanity documentation. You may need to update your component code to match changes in the Sanity API.

Impact on Existing Content

The list numbering fix typically doesn't require changes to your existing content's data structure. However, it's worth understanding how the upgrade affects your content ecosystem.

Will Existing Content Need to be Updated?

In most cases, no manual updates are needed for existing content. The fix primarily affects how the Portable Text Editor handles new lists and renders existing ones, not the underlying data structure.

However, if you've implemented workarounds for the list numbering issue (like custom rendering components), you may need to remove these workarounds to avoid conflicts with the official fix.

Content Audit Recommendations

If your site relies heavily on numbered lists, consider performing a content audit:

1. Identify documents with multiple numbered lists
2. Review how these lists appear in the updated Studio
3. Check how they render on your frontend
4. Document any inconsistencies for follow-up

Frontend Rendering Considerations

If you're using custom rendering for Portable Text on your frontend, ensure your rendering logic aligns with the fixed behavior. In particular, check any code that handles list rendering and numbering.

Preventing Future Issues

To minimize the impact of similar issues in the future:

Stay Current with Sanity Updates

Implement a regular update schedule for your Sanity installation:

1. Subscribe to the Sanity release notes
2. Schedule monthly or quarterly dependency updates
3. Test updates in a development environment before deploying

Establish a Testing Protocol

Create a simple testing protocol for your content editors to follow after each upgrade:

• Test basic editing functionality
• Create and edit documents with complex structures
• Verify that numbered lists work correctly
• Check that any custom components continue to function

Maintain a Feedback Loop

Encourage content editors to report issues immediately:

• Create a dedicated Slack channel or issue tracker for CMS issues
• Document known issues and workarounds
• Share updates and fix announcements with your content team

Version Management Strategy

Consider implementing a more formal version management strategy:

// Example package.json with pinned versions{  "dependencies": {    "sanity": "3.53.0",    "@sanity/client": "3.4.1",    // Other dependencies...  }}

Using exact versions (without ^ or ~) gives you more control over when updates occur, allowing for planned upgrade cycles.

Conclusion

The numbered list reset bug in Sanity CMS has been a significant pain point for content editors, but with the release of version 3.53.0, this issue has been officially resolved. By following the upgrade process outlined in this guide, you can provide your content team with a smoother, more intuitive editing experience.

Key takeaways from this guide:

• The numbered list bug was fixed in Sanity version 3.53.0
• Upgrading is the recommended solution, as it provides an official fix
• The upgrade process is straightforward for most installations
• Alternative workarounds exist but are less reliable than the official fix
• Regular updates help prevent similar issues in the future

Remember that maintaining your CMS is an ongoing process. Staying current with updates not only fixes bugs like this one but also provides your team with the latest features and security improvements.

Have you encountered other Sanity Studio issues that need addressing? Share your experiences in the comments below!

Additional Resources

• Official Sanity Documentation
• Sanity Release Notes
• Portable Text Specification
• Sanity Community Forum
• Managing Sanity Dependencies