Configure cascade

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.

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 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, 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: July 27, 2026 : content: Clarify the definition of cascade (45ae53c2d)

Improve this page