Documents

Configuration properties that affect individual document objects.

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

Document Properties

These properties enable you to customize the behavior and visibility of editable documents in Netlify Create.

filterDocument

Filter documents available to be edited in Netlify Create based on the current user context.

Required
No.
Allowed Values
A function that receives a single argument as an object with document and userContext properties and returns a boolean or undefined, specifying whether the document should be available to be edited in Netlify Create, and overriding the hidden property on that document.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
export default {
  filterDocument({ documents, userContext }) {
    // Filtering logic based on current user context ...
    return true
  },
}
  • The filterDocument function is called for every document that is loaded from all content sources. The return value (boolean or undefined) determines if the document is available to be edited in Netlify Create, overriding the hidden property on that document.
    • If hidden is true on a document, returning true from filterDocument will override that and make the document visible and editable.
    • If hidden is false (or undefined) on a document, returning false from filterDocument will override that and hide the document, making it uneditable. Returning undefined from filterDocument will leave the document visible and editable.
  • filterModel is run before filterDocument, and if a model is hidden, all documents of that model will be hidden as well, and filterDocument will not be called for those documents.

mapDocuments (experimental)

This property is experimental. It's currently being used to support localization. Behavior may be rapidly adjusted. Please contact us for more information and to stay updated with the latest changes.

A function that can be used to extend or manipulate documents that Netlify Create retrieves from the content source.

Required
No.
Allowed Values
A function receiving a single argument as an object with a documents property.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
export default {
  mapDocuments({ documents }) {
    return documents.map((document) => {
      return {
        ...document,
        // Add or adjust document properties ...
      }
    })
  },
}
  • This can only be used when the source was defined using contentSources.
  • The function should return an array of documents. Documents not returned from this function will be ignored by Netlify Create.

Document Hook Methods

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

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, Netlify Create 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
  • 14
  • 15
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
  • 3
  • 4
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
  • 2
  • 3
  • 4
const field = options.getDocumentFieldForFieldPath({
  document,
  fieldPath: 'author.firstName',
})

getDocuments

Returns an array of DocumentWithSource objects value of the document in the content source. DocumentWithSource adds srcType and srcProjectId properties to the standard Document object.

Function Parameters

This method uses no parameters.

Usage Example

  • 1
const document = options.getDocuments()

getLogger

Returns a Logger object that can be used to emit messages to the appropriate console, based on the developer's or user's environment and context.

Function Parameters

There are no parameters for this method.

Usage Example

  • 1
const model = options.getLogger()

Return Value

The Logger return value contains functions that can be used to set the context of a message. Each accepts a message string as the sole parameter.

  • 1
  • 2
  • 3
  • 4
  • 5
const logger = options.getLogger()
logger.error('...')
logger.warn('...')
logger.info('...')
logger.debug('...')

getModelByName

Returns 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' })

getSchemas

Returns an array of SchemaWithSource objects, optionally filtered by a specific source.

Function Parameters

The function accepts a single options object, which supports the following properties:

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.

If omitted, the function returns all schemas. Otherwise it will filter by all of the specified properties.

Usage Example

  • 1
  • 2
// Returns all schemas in Contentful content sources
const model = options.getSchema({ srcType: 'contentful' })

Return Value

A SchemaWithSource object has the following properties:

  • context: The schema context
  • locales: A list of locales used within the schema, if applicable.
  • models: An array of Model objects within that schema
  • srcProjectId: Uniquely-identifying string for the content source instance
  • srcType: Property from the content source module

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.