Configure cascade

Configure cascade.

You can configure your site to cascade front matter values to the home page and any of its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor node has already cascaded a value for the same field through its front matter’s cascade key.

You can also configure cascading behavior within a page’s front matter. See details.

For example, to cascade the color page parameter to all pages:

cascade:
  params:
    color: red

[cascade]
  [cascade.params]
    color = 'red'

{
   "cascade": {
      "params": {
         "color": "red"
      }
   }
}

Target

The target key accepts a page matcher to limit cascaded values to a subset of pages.¹ If a target is omitted, values cascade to all pages.

A page matcher filters pages by logical path, page kind, environment, or site. Specify filtering criteria using any combination of the following keywords.

environment: (string) A glob pattern matching the build environment. For example: {staging,production}.
kind: (string) A glob pattern matching the page kind. For example: {taxonomy,term}.
lang: Deprecated in v0.153.0; Use sites instead.
path: (string) A glob pattern matching the page’s logical path. For example: {/books,/books/**}.
sites: New in v0.153.0; (map) A sites matrix matching any combination of content dimensions including language, version, and role.

For example, to cascade the color page parameter to the articles section and its descendants, but only for the English (en) and German (de) language sites:

cascade:
  params:
    color: red
  target:
    path: '{/articles,/articles/**}'
    sites:
      matrix:
        languages: '{en,de}'

[cascade]
  [cascade.params]
    color = 'red'
  [cascade.target]
    path = '{/articles,/articles/**}'
    [cascade.target.sites]
      [cascade.target.sites.matrix]
        languages = '{en,de}'

{
   "cascade": {
      "params": {
         "color": "red"
      },
      "target": {
         "path": "{/articles,/articles/**}",
         "sites": {
            "matrix": {
               "languages": "{en,de}"
            }
         }
      }
   }
}

Array

Define an array of cascade maps to apply different values to different targets. For example:

cascade:
- params:
    color: red
  target:
    path: '{/articles,/articles/**}'
- params:
    color: blue
  target:
    path: '{/tutorials,/tutorials/**}'

[[cascade]]
  [cascade.params]
    color = 'red'
  [cascade.target]
    path = '{/articles,/articles/**}'
[[cascade]]
  [cascade.params]
    color = 'blue'
  [cascade.target]
    path = '{/tutorials,/tutorials/**}'

{
   "cascade": [
      {
         "params": {
            "color": "red"
         },
         "target": {
            "path": "{/articles,/articles/**}"
         }
      },
      {
         "params": {
            "color": "blue"
         },
         "target": {
            "path": "{/tutorials,/tutorials/**}"
         }
      }
   ]
}

The _target alias for target is deprecated and will be removed in a future release. ↩︎

Last updated: May 18, 2026 : content: Updates for v0.161.0 (d98276be3)

Improve this page