Understanding and modifying an existing Sanity project without documentation

Welcome to the community! Great question - diving into an existing Sanity project without access to the original developer is definitely doable. Let me help you get oriented and solve your specific issue with adding a new block type.

Getting Your Bearings on an Existing Project

Here's a practical roadmap for exploring an unfamiliar Sanity project:

1. Start with sanity.config.ts/js - This is your project's main configuration file at the root. It tells you:

• Your project ID and dataset name
• Which plugins are installed
• How schemas are registered
• Any custom Studio configurations

2. Find the schema files - Look for a schemas or schemaTypes folder. This is your blueprint:

• Files that export schema definitions (using defineType or defineField)
• An index.ts/js that usually imports and combines all schema types
• Document types (top-level content) vs object types (reusable components)

3. Identify the field you're working with - Since you're looking at a dropdown in a rich text editor, search your schemas for fields with type: 'array' that contain {type: 'block'} - this is Portable Text.

4. Check the Studio structure - Look at how content types are organized in the Studio UI to understand the project's content model.

Adding a Custom Block Type to That Dropdown

Based on your screenshot showing a dropdown in the Portable Text editor, here's exactly how to add a new block type:

Step 1: Create your custom block schema

Create a new file in your schemas folder (or add to an existing one):

import {defineType, defineField} from 'sanity'

export const myCustomBlock = defineType({
  name: 'myCustomBlock',
  type: 'object',
  title: 'My Custom Block',
  fields: [
    defineField({
      name: 'content',
      type: 'string',
      title: 'Content',
    }),
    // Add whatever fields you need
  ]
})

Step 2: Register it in your schema

Add your new block type to your schema index file where all types are exported (usually schemas/index.ts).

Step 3: Add it to the Portable Text field

Find the schema file that contains the field with that dropdown (likely the main content field for a document type). Look for something like this:

defineField({
  name: 'body', // or 'content', etc.
  type: 'array',
  of: [
    {type: 'block'}, // This is the standard text
    {type: 'image'}, // Existing custom blocks
    {type: 'myCustomBlock'}, // Add your new block here!
  ]
})

Once you save and restart your Studio (if running locally with sanity dev), your new block type should appear in that dropdown!

Important Distinction: Styles vs Block Types

Looking at your dropdown, I need to clarify something important:

• Block Types (what I described above) are for inserting non-text content like images, videos, or custom components between paragraphs
• Styles are for text formatting options like "Heading 2" or "Quote" that appear in the style dropdown

If you're trying to add a text style (like a new heading level), you'd configure it differently:

defineField({
  name: 'body',
  type: 'array',
  of: [
    {
      type: 'block',
      styles: [
        {title: 'Normal', value: 'normal'},
        {title: 'Heading 2', value: 'h2'},
        {title: 'My Custom Style', value: 'myStyle'}, // Add here
      ]
    }
  ]
})

Tips for Working Without the Original Dev

• Be careful with schema changes - Modifying existing schemas can affect existing content
• Test in a development dataset if possible
• Check for any documentation - Look for README files or comments in the code
• Use Studio's built-in tools - The Vision plugin (if installed) lets you query your data with GROQ to understand the structure

If you share more details about what kind of block you're trying to add (is it for inserting custom content, or formatting text?), I can give you more specific guidance!