Docs (Public)

Use Page Models to create content types for markdown files and front-matter.

Page Models have access to all common content model fields.

Overview

Example of modelling an "article" page in the articles folder. Note that the root folder of your content is defined in the stackbit.yaml using the pagesDir field. In this case our content is located in pagesDir: content

# content/articles/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

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

hideContent

Can be 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 must match the field models nested inside the matched page model. You may use the global excludePages to exclude markdown files from matching.

You can control how files are matched to page models using the matching options below.

If no matching options are provided, a page model would use 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 that are not singleInstance

# stackbit.yaml
...
pagesDir: content
models:
  home:
    type: page
    label: Home
    file: "posts/index.md"
    singleInstance: true
  blog:
    type: page
    label: Blog Posts
    folder: posts
├── 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 will be the equivalent of pagesDir

Can be combined with match and exclude matching options. These options become relative to the folder

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 this folder and all files inside
│   │   ├── index.md
│   │   ├── post1.md
│   │   ├── post2.md
│   │   └── post3.md
│   ├── homepage.md       
│   └── about.md
│   └── product.md

Combining exclude with folder

# stackbit.yaml
...
pagesDir: content
models:
  blog:
    type: page
    label: Blog Posts
    folder: posts
    exclude: 
      - "index.md" 
├── 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.

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

The default value is **/* (all files in all subfolders)

match is relative to folder. If folder is not set for a page model the default value of "" will be used, which will be 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.

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

# 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