Models

Models describe the content structure of your site. Models are defined as a map of objects in stackbit.yaml in the models key.

There are three types of models that you can 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.

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

• Allowed values: page, data, object
• Required: true

The type of the model.

Example

models:
  home:
    type: page

label

• Allowed values: string
• Required: true

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".

Example

models:
  home:
    type: page
    label: "Blog Post"

description

• Allowed values: string
• Required: false

Description of the model.

Example

models:
  home:
    type: page
    label: "Blog Post"
    description: "Create a new blog post"

fields

• Allowed values: list of Fields
• Required: true

The fields that that make up the data within the model.

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