Overview

Understand the structure of the `.pages.yml` file.

What .pages.yml does

.pages.yml is the single source of truth for Pages CMS configuration.

Place it at the repository root.

Pages CMS reads it per repository and per branch.

Top-level keys

Key Description
media Defines where uploaded files are stored and what URLs are written. See media.
content Defines editable collections and files. See content.
components Reuses shared field definitions. See components.
settings Sets repository-wide behavior such as merge mode and commit templates. See settings.

Read order

Start with this order:

  1. Define media.
  2. Define content.
  3. Add components if fields repeat.
  4. Add settings if you need global behavior.

Minimal example

media: media
content:
  - name: posts
    label: Posts
    type: collection
    path: content/posts
    fields:
      - name: title
        type: string
      - name: body
        type: rich-text

Example with a collection and a single file

media:
  input: src/media
  output: /media
content:
  - name: posts
    label: Posts
    type: collection
    path: src/posts
    fields:
      - name: title
        type: string
      - name: body
        type: rich-text
  - name: site
    label: Site settings
    type: file
    path: src/_data/site.json
    fields:
      - name: title
        type: string
      - name: description
        type: text
      - name: url
        type: string