Page models are derived from page layouts - for each layout in the layouts folder (except body.html), there should be at least one page model with the following fields (two different page models might use the same layout):

  • type [Required]: the type of page model is always page.
  • label [Required]: 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 various CMS when viewing the lists of folders or "Content Types".
  • description: description of the model. A longer, more descriptive sentence about the page model. For example: "Article is used to write blog posts and appears under the Blog section"
  • layout [Required if pageLayoutKey was set]: the layout used to render pages of this model. Usually, static site generators require every page to have a layout field in their front-matter, linking the page to its layout (the name of the front-matter field is controlled by the pageLayoutKey field). The value of this field should be equal to the the value of the front-matter key specified by the pageLayoutKey. For example, in Hugo, pages that use home.html layout should set this value to home. Note: as explained in Unambiguous Page to Model Mapping section, pages are not required to have a field defined by pageLayoutKey, if and only if, a page file can be unambiguously mapped to its model.
  • singleInstance: Should be set too true for layouts that should have only one page instance (e.g.: home), and false for layouts that can be used by several pages (page.html or post.html). Defaults to false.
  • file [Required if singleInstance: true]: specifies the file path of the markdown page relative to the pagesDir folder.
  • folder: a folder, relative to the pageDir, with markdown files and YAML front-matter data described by this page model. The default value is an empty string, meaning all files in the pageDir folder. For example, for a site with posts located inside a "posts" folder, the "post" model should have this value set to posts. This field is mutually exclusive with singleInstance: true.
  • match: a glob pattern used to match markdown files inside the specified folder. Defaults to all files (**/*). Internally the "micromatch" NPM module is used to match the files. This field is mutually exclusive with singleInstance: true.
  • exclude: a glob pattern used to exclude markdown files inside the specified folder. Defaults to not exclude any files. Internally the "micromatch" NPM module is used to match the files. This field is mutually exclusive with singleInstance: true.
  • hideContent: should be set to true for page models that do not have markdown content (e.g. home.html), and false for page models that can have a markdown content (e.g.: page,html or post.html). Defaults to false.
  • fields: a list of Field Models. Do not include layout or menus, as they will be added automatically by the conversion process.


Modeling an "article" page in the articles folder

Let's say you have some content written in markdown with the following front matter. Depending on your SSG the content might be located in a different folder.


title: How to install Node.js
layout: article
image_thumbnail: images/screenshot.jpg
show_image: true

# Et perhorruit quoque revocataque vellem

## Angue poma dentibus

Aridus nostra abstractus viris
vitataque labores hiatus ultima, favistis Hippothousque vincemus cum, nymphae
[triformis aera quae]( templa.

To create a content type with individual fields that a CMS can understand we need to define it as a page model in the stackbit.yaml (note: the layout is not defined among other front-matter fields but as a property of the model itself):

pagesDir: content     # the root folder of all markdown pages
pageLayoutKey: layout # here we define the name of the front-matter
                      # field responsible for specifying page layout.
    type: page        # page models should always have "page" type
    label: Article
    layout: article   # the value of the key specified by the pageLayoutKey
                      # that should be present in all pages represented by
                      # this model
        folder: articles  # the folder relative to pagesDir where all pages of
                      # this type should be located
      - type: string
        name: title
        label: Title
        description: The title of the page.
        required: true
      - type: string
        name: image_thumbnail
        label: Image
        description: the articles image
      - type: boolean
        name: show_image
        label: Show Image
        description: Show or hide the image