Docs (Public)

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

Page Models have access to all common content model fields.

Overview

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 Fields

layout

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

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

Page Model Matching

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 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: "{

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