Docs

Documents

Configuration properties that affect individual document objects.

Documents are normalized content objects that Stackbit reads and writes from content sources. The properties here allow for extending behavior built into content source modules in Stackbit.

Document Hook Methods

Document hooks provide the ability to perform transformations and other operations on documents, in response to content changes within Stackbit.

onContentCreate

Modify values of documents and their nested objects before these values are transformed into operations to create new documents.

After this method is returned, Stackbit will take the result and call onDocumentCreate for every eligible document contained within the return object.

Required
No
Allowed Values
A function that accepts an options object and returns an object with properties that get transformed into a create operation. See below for options and an example.

Options

The options object contains shared document hook method properties, along with these unique properties:

object

An object with the properties applied to the document by the content editor.

  • Keys are the name of the field.
  • Values are the values input by the content editor.
model
A ModelWithSource object holding meta and schema information about the content model used by the document to be created.
locale
A string representing the current locale.

Usage Example

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
import { defineStackbitConfig } from '@stackbit/types'

export default defineStackbitConfig({
  onContentCreate: (options) => {
    const { object } = options
    // Add a nested placeholder hero section to a page.
    if (options.model.name === 'Page') {
      object.sections = [{ $$type: 'HeroSection', heading: object.title || '[not set]' }]
    }
    // Return the adjusted object.
    return object
  },
})

See the document hooks feature guide for more information and examples.

Reserved Keys

There are reserved keys that can be used to help with nested and reference information.

$$ref
The ID of (or file path to) an existing document, used to link to existing content.
$$type
The name of a model, used to determine and validate the shape of nested objects. This can also be used to create new reference objects.

See the feature guide and Presets API reference for more information.

onDocumentCreate

Perform actions after a user creates a new document, but before that document is stored in the content source.

Required
No
Allowed Values
A function that accepts an options object and returns the options.createDocument function with an adjusted options object. See below for options and an example.

Options

The options object contains shared document hook method properties, along with these unique properties:

createDocumentOptions

An object with the properties to be passed to createDocument in the appropriate content source module.

This is the object to transform before passing to options.createDocument, as described below.

createDocument
A function that should be used as the return value to onDocumentCreate. It accepts a single objects argument, which should match the shape of the content source module's createDocument method.

Usage Example

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
import { defineStackbitConfig } from '@stackbit/types'

export default defineStackbitConfig({
  onDocumentCreate: (options) => {
    const { createDocumentOptions, createDocument } = options
    // Transform `createDocumentOptions` object ...
    // Then pass to `createDocument` as the return value
    return createDocument(createDocumentOptions)
  },
})

See the document hooks feature guide for more information and examples.

onDocumentDelete

Perform actions after a user chooses to deletes a document, but before that document is removed from the content source.

Required
No
Allowed Values
A function that accepts an options object and returns the options.deleteDocument function with an adjusted options object, if necessary. See below for options and an example.

Options

The options object contains shared document hook method properties, along with these unique properties:

deleteDocumentOptions

An object with the properties to be passed to deleteDocument in the appropriate content source module.

This is the object to transform before passing to options.deleteDocument, as described below.

deleteDocument
A function that should be used as the return value to onDocumentDelete. It accepts a single objects argument, which should match the shape of the content source module's deleteDocument method.

Usage Example

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
import { defineStackbitConfig } from '@stackbit/types'

export default defineStackbitConfig({
  onDocumentDelete: (options) => {
    const { deleteDocumentOptions, deleteDocument } = options
    // Transform `deleteDocumentOptions` object, or perform some other action(s) ...
    // Then pass `deleteDocumentOptions` to `deleteDocument` as the return value
    return deleteDocument(deleteDocumentOptions)
  },
})

See the document hooks feature guide for more information and examples.

onDocumentsPublish

Perform actions after a user publishes changes, but before the changes are marked as published in the content source.

Required
No
Allowed Values
A function that accepts an options object and returns the options.publishDocuments function with an adjusted options object, if necessary. See below for options and an example.

Options

The options object contains shared document hook method properties, along with these unique properties:

publishDocumentsOptions

An object with the properties to be passed to publishDocuments in the appropriate content source module.

This is the object to transform before passing to options.publishDocuments, as described below.

publishDocuments
A function that should be used as the return value to onDocumentsPublish. It accepts a single objects argument, which should match the shape of the content source module's publishDocuments method.

Usage Example

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
import { defineStackbitConfig } from '@stackbit/types'

export default defineStackbitConfig({
  onDocumentsPublish: (options) => {
    const { publishDocumentsOptions, publishDocuments } = options
    // Transform `publishDocumentsOptions` object, or perform some other action(s) ...
    // Then pass to `publishDocumentsOptions` to `publishDocuments` as the return value
    return publishDocuments(publishDocumentsOptions)
  },
})

See the document hooks feature guide for more information and examples.

onDocumentUpdate

Perform actions after a user updates an existing document, but before the changes are sent to the content source.

Required
No
Allowed Values
A function that accepts an options object and returns the options.updateDocument function with an adjusted options object, if necessary. See below for options and an example.

Options

The options object contains shared document hook method properties, along with these unique properties:

updateDocumentOptions

An object with the properties to be passed to updateDocument in the appropriate content source module.

This is the object to transform before passing to options.updateDocument, as described below.

updateDocument
A function that should be used as the return value to onDocumentUpdate. It accepts a single objects argument, which should match the shape of the content source module's updateDocument method.

Usage Example

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
import { defineStackbitConfig } from '@stackbit/types'

export default defineStackbitConfig({
  onDocumentUpdate: (options) => {
    const { updateDocumentOptions, updateDocument } = options
    // Transform `updateDocumentOptions` object, or perform some other action(s) ...
    // Then pass to `updateDocumentOptions` to `updateDocument` as the return value
    return updateDocument(updateDocumentOptions)
  },
})

See the document hooks feature guide for more information and examples.

Document Hook Options

In addition to the unique properties available in the options object sent to document hook functions, there are a number of properties within options available to all hooks. These are referenced below.

contentSourceActions

An object containing functions to create, update, delete and publish documents in the content source of the current document.

All functions receive an optional userContext. If the userContext is not specified, a default userContext for the current user and the content source will be used.

Calling these functions will trigger onDocument hooks. Therefore, do not use these function to create, update, delete and publish the current document — it will introduce an infinite loop.

Action Functions

The following functions are available on this object.

createDocument
Function that calls createDocument on the content source used by the current document.
deleteDocument
Function that calls deleteDocument on the content source used by the current document.
publishDocuments
Function that calls publishDocuments on the content source used by the current document.
updateDocument
Function that calls updateDocument on the content source used by the current document.

Usage Example

  • 1
options.contentSourceActions.createDocument(options.createDocumentOptions)

getContentSourceActionsForSource

Function that returns an object containing functions to create, update, delete and publish documents in the content source matching the received srcType and srcProjectId. This is typically used to call these actions on a source other than the one used by the current document.

All functions receive an optional userContext. If the userContext is not specified, a default userContext for the current user and the content source will be used.

Calling these functions will trigger onDocument hooks. Therefore, do not use these function to create, update, delete and publish the current document — it will introduce an infinite loop.

Function Parameters

Options passed to this function are shown below.

srcProjectId

string matching the srcProjectId return value of the desired content source.

This is optional. However, if there are multiple content source instances return the same value for srcType, the return value for getContentSourceActionsForSource will be undefined.

srcType
string matching the srcType return value of the desired content source.

Return Value

Unless undefined, the return value will be an object with the following methods.

createDocument
Function that calls createDocument on the content source matched with srcType and srcProjectId.
deleteDocument
Function that calls deleteDocument on the content source matched with srcType and srcProjectId.
publishDocuments
Function that calls publishDocuments on the content source matched with srcType and srcProjectId.
updateDocument
Function that calls updateDocument on the content source matched with srcType and srcProjectId.

Usage Example

  • 1
  • 2
const actions = options.getContentSourceActionsForSource({ srcType: 'mySource' })
if (actions) actions.createDocument(options.createDocumentOptions)

getDefaultLocaleBySource

Returns the default locale of a content source.

Function Parameters

The following should be sent as properties to an options argument passed to the function.

srcType

string (required): Value matching the srcType return value of the desired content source.

If multiple content sources return the same srcType, use srcProjectId to distinguish between them.

srcProjectId
string (optional): Value matching the srcProjectId return value of the desired content source.

Usage Example

  • 1
const locale = options.getDefaultLocaleBySource({ srcType: 'mySource' })

getDocumentById

Returns a Document object using the unique id value of the document in the content source.

Function Parameters

The following should be sent as properties to an options argument passed to the function.

id

string (required): The unique ID value of the object in the content source.

If only one document with the provided id was found among all the content sources, that document will be returned. If more than one document was found, a warning message will be printed to the console and 'undefined' will be returned.

In that case, provide 'srcType' and/or 'srcProjectId' to narrow down the document search.

srcProjectId
string (optional): Value matching the srcProjectId return value of the desired content source.
srcType
string (optional): Value matching the srcType return value of the desired content source.

Usage Example

  • 1
const document = options.getDocumentById({ id: '123' })

getDocumentFieldForFieldPath

Returns a (non-localized) document field for the provided fieldPath.

Function Parameters

The following should be sent as properties to an options argument passed to the function.

document
object (required): A Document object that includes source properties — srcType (required) and srcProjectId (optional if only one source of srcType).
fieldPath

string (required): Specifies a dot-notation path to a nested field within the provided document. The fieldPath can contain field names of nested objects, referenced documents and their nested objects, and numbers specifying indexes of array items.

fieldPath can be a relative value if used with fromField.

fromField
object (optional): - A field object used as the prefix to resolve fieldPath in a nested document.
locale
string (optional): A locale value used to resolve localized fields. If not provided, the default locale for the document's content source is assumed.

Usage Example

  • 1
const field = options.getDocumentFieldForFieldPath({ document, fieldPath: 'author.firstName' })

getModelByName

Return a Model object by matching the name property.

Function Parameters

The following should be sent as properties to an options argument passed to the function.

modelName

string (required): The unique name property value of the model in the content source.

If only one document with the provided id was found among all the content sources, that document will be returned. If more than one document was found, a warning message will be printed to the console and 'undefined' will be returned.

In that case, provide 'srcType' and/or 'srcProjectId' to narrow down the document search.

srcProjectId
string (optional): Value matching the srcProjectId return value of the desired content source.
srcType
string (optional): Value matching the srcType return value of the desired content source.

Usage Example

  • 1
const model = options.getModelByName({ modelName: 'Page' })

getUserContextForContentSourceType

Returns the userContext of the current user for the content source specified by srcType. This can be used to create, update, delete and publish documents on behalf of the current user.

Generally, userContext is not used, as it will be applied automatically as the current user.

Function Parameters

Options passed to this function are shown below.

srcType
string matching the srcType return value of the desired content source.

Return Value

A user context object is returned, which can be passed as the userContext property when using a document action. Typically, this is not needed.

Usage Example

  • 1
const userContext = options.getUserContextForContentSourceType('mySource')

srcProjectId

The content source project ID of the current document (string), set by the content source module. This is usually passed as an option when instantiating the content source module.

srcType

The content source type of the current document (string), set by the content source module.