Here are all properties that are defined at the model level, i.e. not under a specific field.
Allowed values: The model's name. Names should only contain alphanumeric characters or an underscore, and must start with a letter.
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.
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.
Allowed values: A human readable label for the field.
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.
Allowed values: The name of an existing field in this model - whose value best describes the specific content item.
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.
Allowed values: A list of one or more model names
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
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.
Allowed values: List of strings
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
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
name: PageLayout label: Page fields: - type: list name: sections items: type: model groups: - sectionComponent
Allowed values: List of objects, each with a
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 ...
Allowed values: true/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
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.
Allowed values: A list of objects, each defining one field.
Field properties are covered in detail in the next chapter.