Here are all properties that are defined at the model level, i.e. not under a specific field.
name
Allowed values: The model's name. Names should only contain alphanumeric characters or an underscore, and must start with a letter.
Required: Yes
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. It is recommended to use names with all initial letters capitalized, e.g. CaseStudySection
.
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.
label
Allowed values: A human readable label for the field.
Required: No
Default: If omitted, the name
of the model is used, with all initial letters capitalized.
A short, descriptive name for the model that is shown to the content editor in various elements of our UI. You can freely change it without breaking any other models or content, e.g. when adding a new page or in the CMS view.
labelField
Allowed values: The name of an existing field in this model - whose value best describes the specific content item.
Required: No
Default: If there's a field in the model called "title", this will be default. Otherwise, "label" if such as field exists, and as a last fallback: the first field of type string that the UI encounters.
This property is used by the editor UI to make it easier to navigate between and within pages. Whenever a content item name is shown in the UI, e.g. in the CMS view, in the site navigation widget or in other places, the value of this field in that content item will be used to label the item.
extends
Allowed values: A list of one or more model names
Required: No
Default: None
The model will inherit all fields in the models included in the list. This model can then define any new fields of its own (see reference below).
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 over-riden 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.
Here's an example for how the built-in HeroSection
extends Section
:
name: HeroSection
label: Hero section
extends:
- Section
groups:
- sectionComponent
fieldGroups:
- name: styles
label: Styles
- name: settings
label: Settings
fields:
- name: colors
default: colors-f
- name: width
default: wide
- name: height
default: tall
# ...
- type: string
name: title
label: Title
default: This Is A Big Hero Headline
Note how some fields only have a name
and a default
, without even a type
. These fields are present in the Section
model - with either a different default or no default at all.
groups
Allowed values: List of strings
Required: No
Default: None
This model-level attribute defines one or more groups in which the model is a member. The attribute works in tandem with the groups
attribute at the field level.
When defining fields of type model
or reference
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 above snippet from the HeroSection
model, the model declares that it belongs in the "sectionComponent" group. Here is how this group name is then used for the "sections" field in the PageLayout
model:
name: PageLayout
label: Page
fields:
- type: list
name: sections
items:
type: model
groups:
- sectionComponent
fieldGroups
Allowed values: List of objects, each with a name
and label
property.
Required: No
Default: None
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.
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).
In the below snippet, two field groups are used, and then the colors
field is assigned to the "styles" group.
name: Section
...
fieldGroups:
- name: styles
label: Styles
- name: settings
label: Settings
fields:
...
- type: enum
name: colors
group: styles
...
hideContent
Allowed values: true/false
Required: No
Default: false
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 the name "Content".
Here's how it looks like in the UI when editing a blog post:
For pages that do not need this functionality, set hideContent: true
.
For this functionality to work, define page model files to have an .md extension. When storing Markdown files, all fields except this one are stored as front matter. The content field is then the actual Markdown text below the front matter. For pages whose model declared hideContent: true
, you will find only front matter in files.
Our built-in components expect this field value to be available in a property named markdown_content
under the content object passed to them for rendering. For example, look for page.markdown_content
in our PostLayout component.
In our themes, this property is added to relevant content objects as they're read from files. For more information, see How Stackbit Themes Work. You can fully customize this behavior with your own themes and components.
fields
Allowed values: A list of objects, each defining one field.
Required: Yes
Field properties are covered in detail in the next chapter.