Docs

References

Properties that handle how references are handled when creating new documents.

There are two cases in which Stackbit needs to know how to handle presets when new content is created:

In both cases, Stackbit needs to know how to handle referenced content. By default, Stackbit will not create new documents, but will reuse the references. This behavior can be configured.

Reference Behavior

These properties determine how Stackbit handles references when new documents are created from existing documents or using presets.

Each preset's behavior is determined by the JSON file for that preset. This means that your configuration values for handling references only applies to the point at which the preset is created, after which the JSON file determines the behavior of the preset.

duplicatableModels

When referenceBehavior is set to copyReference, this field specifies a list of exceptions.

Required
No
Allowed Values
An array of strings matching names of content models.
  • 1
  • 2
  • 3
  • 4
  • 5
export default {
  referenceBehavior: 'copyReference',
  duplicatableModels: ['Post'],
  // other properties ...
}
  • If a model appears in this list, it will be duplicated. All other models respect the copyReference setting.

nonDuplicatableModels

When referenceBehavior is set to duplicateContents, this field specifies a list of exceptions.

Required
No
Allowed Values
An array of strings matching names of content models.
  • 1
  • 2
  • 3
  • 4
  • 5
export default {
  referenceBehavior: 'duplicateContents',
  nonDuplicatableModels: ['Post'],
  // other properties ...
}
  • If a model appears in this list, it will NOT be duplicated. All other models respect the duplicateContents setting.

referenceBehavior

Specifies how to handle references when creating new content containing a reference.

Required
No
Alias
presetReferenceBehavior
Allowed Values

copyReference: references are copied directly. The new content will use the same references as the original content. (See duplicatableModels for providing exceptions.)

duplicateContents: Reference(s) are duplicated. The new content will refer to the newly duplicated content and will not affect the original referenced content. (See nonDuplicatableModels for providing exceptions.)

Default
copyReference
  • 1
  • 2
  • 3
  • 4
export default {
  referenceBehavior: 'duplicateContents',
  // other properties ...
}
  • This affects only newly-created presets. Changing this value (or adjusting the exceptions below) have no affect on existing content created from presets. This is because preset configurations are stored as files and Stackbit will not adjust existing files in your repository.
  • Example: A PostFeed component preset includes a reference to a list of featured posts.
    • copyReference: New content created from the preset will refer to the same posts stored in the preset.
    • duplicateContents: Each post referenced in the preset will be duplicated, and the new posts will be used for the new content.