How to reference nested objects with slugs in Sanity Table of Contents?

The issue you're encountering is a fundamental limitation of Sanity's reference system: references can only point to documents, not to objects. This is by design in Sanity's content architecture.

Why References Only Work with Documents

In Sanity, the reference field type creates relationships between documents by storing a _ref field that points to another document's _id. Objects (nested content within documents) don't have top-level _id values that can be referenced in this way—they only exist as part of their parent document.

Solutions for Your Table of Contents

You have a few options to work around this limitation:

1. Convert ToC Items to Documents

If you need to reference individual ToC items, make them proper documents instead of nested objects:

{
  name: 'tocItem',
  type: 'document',
  fields: [
    {name: 'title', type: 'string'},
    {name: 'slug', type: 'slug'},
    // other fields
  ]
}

Then your main ToC document can reference these:

{
  name: 'tableOfContents',
  type: 'document',
  fields: [
    {
      name: 'items',
      type: 'array',
      of: [{type: 'reference', to: [{type: 'tocItem'}]}]
    }
  ]
}

2. Use Path-Based Linking

Instead of references, store the path or identifier as a string and resolve it in your frontend:

{
  name: 'link',
  type: 'object',
  fields: [
    {name: 'tocPath', type: 'string'}, // e.g., "toc.items.0"
    {name: 'slug', type: 'slug'}
  ]
}

3. Query-Based Approach

Keep your ToC as nested objects and use GROQ queries to find and link to them by slug or other identifying properties. In your frontend, you'd query the ToC document and find the matching item by its slug.

4. Hybrid: Generate Pages from Documents

If you're generating Gatsby pages, consider whether you actually need the ToC items as separate entities. You might create a document type specifically for pages that also maintains the ToC structure:

{
  name: 'page',
  type: 'document',
  fields: [
    {name: 'title', type: 'string'},
    {name: 'slug', type: 'slug'},
    {name: 'tocPosition', type: 'number'}, // for ordering
    {name: 'parent', type: 'reference', to: [{type: 'page'}]} // for hierarchy
  ]
}

Key Takeaway

The Sanity documentation is clear on this: references work with documents only. As stated in the reference type docs, the to property must point to document types, and the system uses document _id values for the relationship. There's no way to make references point to nested objects because they lack the necessary _id infrastructure.

Choose the approach that best fits your content model—typically converting to documents if you need true referential relationships, or using path/slug-based linking if you want to keep the nested structure.