Page models - Documentation

Page Models describe the content contained within the markdown files that have front-matter.

Page Models share the common model properties.

To better understand what a page model does, let's look at the following example that models an "article" page in the articles folder. Note that the root folder of your content is defined within the stackbit.yaml using the pagesDir field. In this case our content is located in pagesDir: content.

content/aritcles/installing-node.md

---
title: How to install Node.js
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](http://aether-diurnos.io/tamen.aspx) templa.

The corresponding page model defined in the stackbit.yaml will turn all markdown files in the articles folder into Article content types.

stackbit.yaml

pagesDir: content # the root folder of all markdown pages
models:
  article:
    type: page # page models should always have "page" type
    label: Article
    folder: articles # the folder where these markdown files are located
    match: 
      - "**/*" # match all files and subfolders in the articles folder
    exclude:
      - "index.md" # exclude a file in the articles folder
    fields: # field models
      - 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

Page Model Properties

`layout`

Example value: page
Allowed values: any
Default value: none
Required: required when pageLayoutKey is defined
Contexts: theme, studio-git

The layout used to render pages of this model. This field is optional unless a pageLayoutKey was set in configuration section of the stackbit.yaml, whereby it becomes required.

Many static site generators include a layout field in their front matter by default. layout allows the mapping of pages to content models via this key Note that while layout is a common front matter field, the name of the field in the front matter does not need to be layout and can be defined via the pageLayoutKey. The value of this field should be equal to the value of the front-matter key specified by the pageLayoutKey.

Here's an example to better illustrate the concept. In stackbit.yaml we've defined pageLayoutKey: layout to indicate that the front matter key for defining a layout is called layout. Our template has two layouts defined, layout: home for the home page and layout: blog for any blog posts. We could then define two content models (home and posts) and specify layout: home for the home content model and layout: blog for the posts content model. This would associate our home content model with any pages with the home layout assigned and associate the posts content model with any page that have the blog layout assigned.

For a further, code-based example check the documentation for pageLayoutKey.

`hideContent`

Example value: true
Allowed values: true or false
Default value: false
Required: false
Contexts: theme

Set to true for page models that do not have markdown content.

`urlPath`

Example value: /blog/{slug}
Allowed values: a valid URL path to one of the site pages
Default value: /{slug}
Required: false
Contexts: theme, studio-git

This can either be a fixed path for pages that have a single instance or a pattern for dynamic routes. Dynamic values are indicated by curly braces ({ and }) and should represent a value that is available on the model. For example, a blog post model likely has a slug property representing the path to the specific post within the blog, so a post model might have a urlPath of /blog/{slug}.

Example:

models:
  
  # the keys of the map are the names of the models, as defined in CMS
  home:
    # page models should always have "type" set to "page"
    type: page
    # true allows the creation of only a single instance of this page
    singleInstance: true
    # the url pattern of the page, can include tokens
    urlPath: "/"

  page:
    type: page
    urlPath: "/{slug}"

  post:
    type: page
    urlPath: "/blog/{slug}"

  post_category_list:
    type: page
    # Here the url pattern uses two tokens - "category" and "slug"
    # The "post_category_list" model should have these two fields
    urlPath: "/blog/{category}/{slug}"

  category:
    # when creating or duplicating a page with a field that references
    # this model, it will use an existing category object rather than 
    # creating a new one
    type: data

Page Model Matching Properties

Each markdown file in your themes pagesDir must match a single page model. If a file matches multiple page models you will get a validation error.

The front-matter within a matched page must line up with the field models nested inside the page model that it matched. You may use the global excludePages to exclude markdown files from matching.

For more details about pagesDir and excludePages, check the stackbit.yaml documentation page.

You can control how files are matched to page models using the configuration options below. If no matching options are provided, a page model uses the following defaults:

folder: ""
match: "**/*"
exclude: []

`file`

Matches a single markdown file relative to the pagesDir folder.

Cannot be combined with folder, match and exclude matching options.

Required if singleInstance: true

stackbit.yaml

pagesDir: content
models:
  home:
    type: page
    label: Home
    file: "homepage.md"

├── stackbit.yaml
├── content
│   ├── posts
│   │   ├── index.md
│   │   ├── post1.md
│   │   ├── post2.md
│   │   └── post3.md
│   ├── homepage.md       # will match this file
│   └── about.md
│   └── product.md

`singleInstance`

Should be set too true for files that should have only one page instance (e.g.: home). If a file is marked as singleInstance in one model then you don't need to exclude it in all the other models.

For example, given the following configuration with two page models:

stackbit.yaml

pagesDir: content
models:
  home:
    type: page
    label: Home
    file: "posts/index.md"
    singleInstance: true
  blog:
    type: page
    label: Blog Posts
    folder: posts

The home model marked as singleInstance will match index.md while the blog model will match all other files in the posts folder. There won't be a validation error because index.md does not need to be excluded from the blog model as it was matched by a singleInstance model.

├── stackbit.yaml
├── content
│   ├── posts
│   │   ├── index.md    # "home" will match this file but "blog" will skip it because "home" uses singleInstance   
│   │   ├── post1.md    # "blog" will match this file
│   │   ├── post2.md    # "blog" will match this file
│   │   └── post3.md    # "blog" will match this file
│   ├── homepage.md       
│   └── about.md
│   └── product.md

`folder`

Matches all markdown files inside a folder relative to the pagesDir folder.

The default value for folder is an empty string. If folder is not set for a page model the default value will be used, which means it will match all .md files under pagesDir.

This value can be combined with the match and exclude matching options to fine tune the files that are match. These options are relative to the folder when it is defined. For example, if the folder value was posts and the match value was ["index.md", "about.md"], the content model would match posts/index.md and posts/about.md.

This field is mutually exclusive with singleInstance: true.

stackbit.yaml

pagesDir: content
models:
  blog:
    type: page
    label: Blog Posts
    folder: posts

├── stackbit.yaml
├── content
│   ├── posts           # will match all files inside this folder
│   │   ├── index.md
│   │   ├── post1.md
│   │   ├── post2.md
│   │   └── post3.md
│   ├── homepage.md       
│   └── about.md
│   └── product.md

The following is an example of combining exclude with folder:

stackbit.yaml

...
pagesDir: content
models:
  blog:
    type: page
    label: Blog Posts
    folder: posts
    exclude: 
      - "index.md"

All files other than the excluded file will be matched. However, [index.md](http://index.md) would still need to match a separate page model.

├── stackbit.yaml
├── content
│   ├── posts
│   │   ├── index.md    # will exlcude this file
│   │   ├── post1.md    # will match this file
│   │   ├── post2.md    # will match this file
│   │   └── post3.md    # will match this file
│   ├── homepage.md       
│   └── about.md
│   └── product.md

`match`

A glob pattern used to match markdown files. match supports both glob and list values. The following examples all achieve the same match:

match: ["index.md", "about.md"]
match: "{index.md,about.md}"
match:
  - "index.md"
  - "about.md"

The default value is **/*, which will match all the files in all subfolders as specified by the folder vale for the page model. match is relative to folder. If folder is not set for a page model the default value of "" is used, which is the equivalent of pagesDir.

Internally the "micromatch" NPM module is used to match the files.

This field is mutually exclusive with singleInstance: true

stackbit.yaml

pagesDir: content
models:
  basicpage:
    type: page
    label: Basic Page
    match: 
      - "*.md"

├── stackbit.yaml
├── content
│   ├── posts
│   │   ├── index.md
│   │   ├── post1.md
│   │   ├── post2.md
│   │   └── post3.md
│   ├── index.md       # will match this file
│   └── about.md       # will match this file
│   └── product.md     # will match this file

`exclude`

A glob pattern used to exclude markdown files inside the specified folder. The paths listed must be relative to folder.

By default it does not exclude any files.

Internally the "micromatch" NPM module is used to match the files.

This field is mutually exclusive with singleInstance: true

stackbit.yaml

pagesDir: content
models:
  basicpage:
    type: page
    label: Basic Page
    match: "*.md"
    exclude: 
      - "_index.md"

├── stackbit.yaml
├── content
│   ├── posts
│   │   ├── post1.md
│   │   ├── post2.md
│   │   └── post3.md
│   ├── _index.md      # will exclude this file
│   └── about.md       # will match this file
│   └── product.md     # will match this file

Ready to get started?

Try Stackbit Now