Models

Models map your theme's content to a structured schema. Models are defined in the stackbit.yaml under the models key. The three primary types of models that you will work with are:

• Page Models, representing page based content (e.g. .md files).
• Data Models, representing file-based structured data (e.g. YAML, TOML or JSON files).
• Object Models, representing objects nested within Page and Data models.

Example

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 field models.

stackbitVersion: ~0.2.0
models: # top level models key
  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: # array of field models, must be nested under a model
      - type: string
        name: title
        label: Title
  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

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
• Contexts: all

type 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
• Contexts: theme, studio-git

label 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
• Contexts: theme, studio-git

description 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
• Contexts: theme, studio-git

fields example

models:
  home:
    type: page
    label: "Blog Post"
    description: "Create a new blog post"
    fields:
      - type: string # field model of type: string
        name: title # name maps to the field in the front matter
        label: Title

Studio context

Although models are applicable to all contexts, only specific model types and specific properties should be used in studio context.

• Page models should only specify type, singleInstance and urlPath
• Data models should only specify type
• Object models should not be used in studio context

Studio context example

# stackbit.yaml
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