Model Properties
Options available within a single content model definition in Stackbit.
The models
property is how content models are specified in Stackbit. This document details the properties available within a model definition.
Usage
Each model is defined as a property within the models
property on the primary Stackbit configuration object. The name of the property indicates the name of the model (or ID, in some CMSs), while the value is the model definition.
In the example below, we're showing a configuration that defines two models — Page
and Post
. Within each of these objects can be the options shown below.
1
2
3
4
5
6
7
8
9
10
11
See the name
property for model naming limitations.
Legacy YAML Configuration
If using the legacy YAML configuration, note that you do not need to use the models
property, but can instead place individual model definitions in the .stackbit/models
directory.
Model Definition Options
The following properties are available when configuring a model definition.
actions
Model actions match global and bulk custom actions, except for the following differences:
type
is inferred and not requiredmodel
anddocument
are available within thestate
andrun
options parameter, referring to the document and model on which the action is performed.contentSourceActions
is also available to therun
function. This is an object that includes the following functions that get passed onto the content source module:createDocument
updateDocument
deleteDocument
publishDocuments
description
Description of the model.
1
2
3
4
5
6
7
extends
Models that are extended from other models inherit all fields in the models included in the list. This model can then define any new fields of its own.
1
2
3
4
5
6
7
8
9
10
- If this model declares a field with the same name as a field it inherited, then that field's attributes are merged: any field attributes explicitly set in this model are used. Then, inherited field attributes are used as long as they as not overridden in the model.
- That means you can not only override field attributes fully, but also easily add/change specific attributes of inherited fields, e.g. setting a
default
for a field which better matches this model.
- That means you can not only override field attributes fully, but also easily add/change specific attributes of inherited fields, e.g. setting a
fieldGroups
This attribute is used by the editor UI to visually place related fields in separate groups. This has no effect on the content itself or how it is stored - it is only used to make editing content pieces with multiple fields easier.
This attribute works in tandem with the group
attribute for fields.
1
2
3
4
5
6
7
8
9
10
11
- Any field that does not has an assigned group is put by the editor UI under the default group "Content" (regardless of whether any field groups were defined).
Available
icon
values are listed until the icon control in our component playground.Field groups icon component control
fields
The definition for specifying or overriding fields on a model.
1
2
3
4
5
6
7
8
9
filePath
The path at which to store new page and data content created by editors using Stackbit's application. Stackbit stores new pages at {pagesDir}/{filePath}
and non-pages under {dataDir}/{filePath}
.
1
2
3
4
5
6
7
8
9
- Single-instance models should point to a specific file, while models with multiple content objects should use variable interpolation to create dynamically-named pages.
- Variables can be interpolated using curly brackets. Examples:
filePath: '{slug}.md'
filePath: 'posts/{moment_format(date, 'YYYY-MM-DD')}-{slug}.yaml'
- The UI has special handling for index pages:
- When a user adds a new page and sets its path it
/plans/
(note the trailing slash!), the page content will be stored to the file/content/pages/plans/index.md
- When you navigate to this page, the UI will know to map the URL
/plans/
back to/content/pages/plans/index.md
.
- When a user adds a new page and sets its path it
groups
Adds the model to a specific group for use with the groups
field attribute.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
- When defining fields of type
model
orreference
which point to other model names, you may wish to have a list of acceptable model names which is not hard-coded, e.g. "any section-like component is applicable for nesting here", or "any person-like component can be referenced from here". - In the example above, the
CaseStudySection
model declares that it belongs in theSectionComponent
group. Here is how this group name is then used for thesections
field in thePage
model.
hideContent
By default, the UI assumes that any page models implicitly have a content field with Markdown-formatted content. When the page is edited in the UI, this field will be available to edit under a field labeled Content.
1
2
3
4
5
6
7
- For this functionality to work, defined page model files must have an .md extension.
- For pages whose model declared
hideContent: true
, you will find only front matter in files. - Content for a page where
hideContent
isfalse
is available in a property namedmarkdown_content
.
label
A short, descriptive name for the model that is shown to the content editor in various elements of our UI.
1
2
3
4
5
6
7
- Because this is only for display purposes, you can freely change it without breaking any other models or content.
labelField
Used by the visual editor to make it easier to navigate between and within pages. Whenever a content item name is shown in the editor, the value of the field in that content item will be used to label the item.
1
2
3
4
5
6
7
8
9
10
11
12
13
name
The unique name of the model, which is often the ID for API CMSs. This is not a title or label, which are typically used only for display purposes.
1
2
3
4
5
6
7
8
9
- The model's name is used whenever an instance of this model is stored or this model is referenced anywhere, and thus it typically should not be changed. When you have control over the name of the model, we suggest using PascalCase (e.g.
CaseStudySection
). - If using Git CMS, the model name is included in all content items via their
type
attribute, which is automatically set by Stackbit when the content is stored. In other words, the model name is the content type.
readOnly
Prevents documents of this model from being created or deleted.
This is useful for global, singleton models, which are typically used to affect globally-shared content on the site, such as settings, styles, and default SEO values.
1
2
3
4
5
6
7
- This does not prevent a document's fields from being edited. Read-only fields must be defined at the field level.
type
The type of the model. Learn more about model types.
1
2
3
4
5
6
7
page
anddata
must also specify thefilePath
property.page
must specify theurlPath
property.- Setting
page
will enable the ability to create new pages in the visual editor. To ensure this works properly, you must do both of the following:
urlPath
The urlPath
setting tells Stackbit how to build the sitemap by providing a path for all of a model's page.
1
2
3
4
5
6
7
8
- Values inside curly braces are interpolated to resolve individual page properties. For example, if the
urlPath
were set to/blog/{id}
, Stackbit will retrieve all documents of the model and use each one'sid
property to build an array of paths for the sitemap — e.g.["/blog/1", "/blog/2", "..."]
. For singleton models (models with only a single document), the
urlPath
can be hard-coded to explicitly what the path should be. Example for a model that holds a single blog feed page:1
2
3
4
5
6
7
8