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 a “color” parameter to the home page and all its descendants:

cascade:
  params:
    color: red
title: Home

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

{
   "cascade": {
      "params": {
         "color": "red"
      }
   },
   "title": "Home"
}

Target

The target¹ keyword allows you to target specific pages or environments. For example, to cascade a “color” parameter to pages within the “articles” section, including the “articles” section page itself:

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

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

{
   "cascade": {
      "params": {
         "color": "red"
      },
      "target": {
         "path": "{/articles,/articles/**}"
      }
   }
}

Use any combination of these keywords to target pages and/or environments:

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: (string) A glob pattern matching the page language. For example: {en,de}.
path: (string) A glob pattern matching the page’s logical path. For example: {/books,/books/**}.

Array

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

cascade:
- params:
    color: red
  target:
    kind: page
    lang: '{en,de}'
    path: '{/books/**}'
- params:
    color: blue
  target:
    environment: production
    kind: page
    path: '{/films/**}'

[[cascade]]
  [cascade.params]
    color = 'red'
  [cascade.target]
    kind = 'page'
    lang = '{en,de}'
    path = '{/books/**}'
[[cascade]]
  [cascade.params]
    color = 'blue'
  [cascade.target]
    environment = 'production'
    kind = 'page'
    path = '{/films/**}'

{
   "cascade": [
      {
         "params": {
            "color": "red"
         },
         "target": {
            "kind": "page",
            "lang": "{en,de}",
            "path": "{/books/**}"
         }
      },
      {
         "params": {
            "color": "blue"
         },
         "target": {
            "environment": "production",
            "kind": "page",
            "path": "{/films/**}"
         }
      }
   ]
}

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

Last updated: March 5, 2025 : content: Consolidate configuration documentation (b6cae5cbc)

Improve this page