Models describe the content structure of your site. Models are defined as list of objects in stackbit.yaml
in the models
key.
There are three types of models that you will work with:
- Page Models describe the pages of your site stored in markdown files (e.g.
.md
,.mdx
,.markdown
). - Data Models describe the arbitrary data of your site stored in data files (e.g.
.yml
,.toml
,.json
). - Object Models describe the objects nested within Page and Data models.
type: page
), if they are singleInstance
pages, and their urlPath
.
Example for project without a headless-CMS
Assume a site with the following content structure:
├── content
│ └── posts
│ ├── post1.md
│ └── post2.md
├── data
│ └── config.yaml
└── stackbit.yaml
The stackbit.yaml
would define 2 models. 1 page model representing the posts and 1 data model representing the config. Inside each of these models are the corresponding fields.
stackbitVersion: ~0.3.0
...
dataDir: data
pagesDir: content
models:
article: # a model called "article"
type: page # this is a page model
label: Article
folder: posts # matches all markdown files in the "content" folder
fields: # list of model fields
- type: string
name: title
label: Title
- type: image
name: featuredImage
label: Featured Image
config: # a model called "config"
type: data # this is a data model
label: Config
file: config.yaml # matches a single file
singleInstance: true
fields:
- type: string
name: title
label: Sites Title
- type: image
name: logo
label: Path to Logo Image
Example for project with a headless-CMS
stackbitVersion: ~0.3.0
...
models:
home:
type: page
singleInstance: true
urlPath: "/"
page:
type: page
urlPath: "/{slug}"
post:
type: page
urlPath: "/blog/{slug}"
author:
type: data
Models Naming Rules
As shown above, models are named as keys within the YAML file and must adhere to the following rules:
- Must start with and end with a letter
- Can contain only lower case alphanumeric characters or underscores
_
Model Types
Models must be one of the following types:
page
: Models that represent Page Models. Settings and fields that define the content structure of a specific page type with common front matter fields. For example, the "home" page model might define the content structure of a site's home page, while the "article" page model could define the content structure of blog posts.data
: Models that represent Data Models. Settings and fields that defining the content structure of a data file (e.g. YAML, TOML or JSON). For example, "header" and "footer" data models might define the content structure of a site's header.yml and footer.json data files.object
: Models that represent Object Models. A model that defines the content structure of an arbitrary object that can be reused by being referenced by another object model, data model or page model. For example, a site's home page might have multiple sections, where the model of each section is defined by a separate Object Model. Another example is an object model defining commonly used UI components such as an action button with predefined properties (label, url, color, etc.).
Common Model Properties
type
The type of the model.
- Allowed values:
page
,data
,object
- Required: true
Example
models:
home:
type: page
label
A short, descriptive name for the page model. For example if you were creating a page model for blog content you might use the label "Blog" but you could also use "Article". The label is often displayed in the CMS when viewing the lists of folders or "Content Types".
- Allowed values: string
- Required: true
Example
models:
home:
type: page
label: "Blog Post"
description
Description of the model. In some CMS, the description is shown beside models in model lists.
- Allowed values: string
- Required: true
Example
models:
home:
type: page
label: "Blog Post"
description: "Create a new blog post"
fields
The fields that that make up the data within the model.
- Allowed values: List of Fields
- Required: true
Example
models:
home:
type: page
label: "Blog Post"
description: "Create a new blog post"
fields:
- type: string # field of type: string
name: title # name maps to the field in the front matter
label: Title