Configure cascade

To cascade a value is to apply front matter values from a branch page or the project configuration to descendant pages. Hugo does not cascade a value if the descendant already defines the field, or if a closer ancestor branch or an earlier element in a cascade array has already set a value for the same field. Use a page matcher to limit cascading to a subset of pages.

Use the cascade configuration to pass values down to pages. Hugo supports two forms: a map form for a single cascade, and an array form for applying different values to different subsets of pages. Both forms support the target key.

Map form

Define a single cascade map. For example, this configuration cascades the color page parameter to all pages:

cascade:
  params:
    color: red

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

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

Array form

Define an array of cascade maps to apply different values to different subsets of pages. For example, this configuration cascades a different color page parameter to each of the articles and tutorials sections and their descendants:

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/**}"
         }
      }
   ]
}

Target

In both the map form and the array form, the optional target key accepts a page matcher to limit cascaded values to a subset of pages. If you omit target, 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 the sites setting 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, this configuration cascades 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}"
            }
         }
      }
   }
}