# Hugo Frontmatter Parsing, Validation, and Parameter Inheritance: The Complete Guide > Master Hugo frontmatter parsing validation and parameter inheritance Understand Hugo's sequential processing cascade rules and frontmatter handler for efficient content management - Repository: [GoHugo.io/hugo](https://github.com/gohugoio/hugo) - Tags: deep-dive - Published: 2026-02-28 --- **Hugo processes frontmatter through three sequential phases: initial map sanitization and validation, configurable date resolution via `FrontMatterHandler`, and hierarchical parameter inheritance using cascade rules that respect existing page values.** Hugo's static site generator transforms raw frontmatter into structured page metadata through a sophisticated pipeline implemented in the `gohugoio/hugo` repository. This article examines the actual source code to explain how Hugo parses frontmatter, validates configuration, and inherits parameters through cascade rules. ## Frontmatter Parsing and Basic Validation When Hugo reads a content file, it extracts the frontmatter block and converts it into a `map[string]any`. The system immediately begins normalization and validation before mapping values to internal `Page` structures. ### Map Sanitization with PrepareParams The first operation calls `hmaps.PrepareParams` to normalize the raw frontmatter map. This function lower-cases all keys and ensures case-insensitive lookup safety: ```go hmaps.PrepareParams(frontmatter) ``` This sanitization occurs in [`resources/page/pagemeta/page_frontmatter.go`](https://github.com/gohugoio/hugo/blob/main/resources/page/pagemeta/page_frontmatter.go) before any type-specific processing begins. ### Early Content-Type Resolution After sanitization, `PageConfigEarly.SetMetaPreFromMap` extracts critical metadata keys like `markup` and `sites`, then resolves the content type: ```go if v, found := frontmatter[pageMetaKeyMarkup]; found { pcfg.Content.Markup = cast.ToString(v) } ``` The system uses `mediaTypes.GetBestMatch` to determine the final content type based on these early values. ### Resource Configuration Validation For page-bundle resources, Hugo performs strict validation via `ResourceConfig.Validate`. This method explicitly forbids setting the `markup` key in resource frontmatter, requiring it to be declared via `mediaType` instead: ```go func (rc *ResourceConfig) Validate() error { if rc.Content.Markup != "" { return errors.New("markup must not be set, use mediaType") } return nil } ``` Located at `resources/page/pagemeta/page_frontmatter.go#L480-L485`, this validation aborts the build with a clear error if violated. ## Date Resolution and Frontmatter-Only Fields Hugo handles date fields and special frontmatter-only values through a dedicated handler system that respects user configuration while providing sensible defaults. ### Configurable Date Field Aliases The date resolution logic is configurable via the site's `frontmatter` configuration. The default configuration, defined in `newDefaultFrontmatterConfig`, specifies fallback chains for each date type: ```go func newDefaultFrontmatterConfig() FrontmatterConfig { return FrontmatterConfig{ Date: []string{fmDate, fmPubDate, fmLastmod}, Lastmod: []string{fmGitAuthorDate, fmLastmod, fmDate, fmPubDate}, PublishDate: []string{fmPubDate, fmDate}, ExpiryDate: []string{fmExpiryDate}, } } ``` Users can override these defaults via `DecodeFrontMatterConfig`, which expands user-provided values and maintains date-field aliases. ### Handler Creation and Execution `NewFrontmatterHandler` constructs a `FrontMatterHandler` that processes all date keys. It creates specific handlers for each date family using `createHandlers`: ```go if f.dateHandler, err = f.createDateHandler(f.fmConfig.Date, func(d *FrontMatterDescriptor, t time.Time) { d.PageConfigLate.Dates.Date = t setParamIfNotSet(fmDate, t, d) }); err != nil { return err } ``` The helper `setParamIfNotSet` stores resolved dates as parameters unless the page already defined that specific param, preventing overwrites. ### Frontmatter-Only Values Certain fields, such as `resources`, can only be supplied via frontmatter and never through other sources. These are stored in `FrontMatterOnlyValues`: ```go type FrontMatterOnlyValues struct { ResourcesMeta []map[string]any } ``` The handler processes these values after date resolution, ensuring they remain exclusive to frontmatter declarations. ## Cascade-Based Parameter Inheritance Hugo implements parameter inheritance through **cascades**, allowing parent pages or site configurations to define default values that propagate to descendant pages unless explicitly overridden. ### Cascade Configuration and Disallowed Keys Cascades are defined under the `cascade` key in site configuration or page frontmatter. `DecodeCascadeConfig` decodes these into `PageMatcherParamsConfig` objects while validating against disallowed keys: ```go if disallowedCascadeKeys[k] { return CascadeConfig{}, nil, fmt.Errorf("key %q not allowed in cascade config", k) } ``` Keys such as `kind`, `path`, and `cascade` itself are forbidden to prevent circular dependencies and structural conflicts. ### Early Cascade Application During `PageConfigEarly` creation in `CompileEarly`, Hugo applies cascade rules in two passes. The first pass processes non-site-specific cascades (those without `sites.matrix`): ```go for cascade := range cascades.All() { if cascade.Target.SitesMatrixCompiled != nil { continue // skip site-specific cascades for now } if !cascade.Target.Match(p.Kind, pi.Base(), conf.Environment(), p.SitesMatrix) { continue } for ck, cv := range cascade.Fields { if done := p.setCascadeEarlyValueIfNotSet(ck, cv); done { break } } } ``` The method `setCascadeEarlyValueIfNotSet` writes values only if not already defined by the page's own frontmatter or previous cascades. For the `sites` field, it forwards values to the `Sites` matrix configuration. ### Site-Specific Matching and Matrix Rebuilding After the early pass builds the page's site matrix, Hugo runs a second pass respecting `sites.matrix` targets. If cascades modify the matrix, Hugo rebuilds it to reflect inheritance: ```go if hadCascadeMatch && !sitesMatrixBaseOnly && !sitesMatrixBefore.Equal(p.Sites.Matrix) { // Matrix has changed, rebuild. p.SitesMatrix = buildSitesMatrixFromSitesConfig(...) } ``` This two-pass approach ensures that site-specific cascade rules apply correctly after the initial inheritance structure is established. ### Final Parameter Composition The completed `Params` map contains: - Values from the page's own frontmatter (highest priority) - Inherited values from matching cascades (only if not already set) - Date values stored via `setParamIfNotSet` These parameters become available to templates as `.Params` and to the rendering pipeline. ## Summary - **Frontmatter parsing** begins with `hmaps.PrepareParams` normalizing keys into a case-insensitive map, followed by early content-type resolution in `SetMetaPreFromMap`. - **Validation** occurs at multiple stages, including `ResourceConfig.Validate` which prevents illegal `markup` declarations in page bundles. - **Date handling** uses configurable handlers created by `NewFrontmatterHandler`, supporting fallback aliases and automatic parameter storage via `setParamIfNotSet`. - **Frontmatter-only fields** like `resources` are stored in `FrontMatterOnlyValues` and processed separately from other metadata. - **Parameter inheritance** implements a two-pass cascade system in `CompileEarly`, first applying global cascades via `setCascadeEarlyValueIfNotSet`, then rebuilding the site matrix for site-specific rules. ## Frequently Asked Questions ### How does Hugo prevent cascade parameters from overwriting existing frontmatter values? Hugo uses the `setCascadeEarlyValueIfNotSet` method in [`resources/page/pagemeta/page_frontmatter.go`](https://github.com/gohugoio/hugo/blob/main/resources/page/pagemeta/page_frontmatter.go) to conditionally apply cascade values. This helper checks whether a parameter key already exists in the page's configuration before writing, ensuring that explicit page frontmatter always takes precedence over inherited cascade values. ### Why does Hugo forbid certain keys like `kind` and `path` in cascade configurations? According to the source code in [`resources/page/page_matcher.go`](https://github.com/gohugoio/hugo/blob/main/resources/page/page_matcher.go), the `DecodeCascadeConfig` function maintains a list of `disallowedCascadeKeys` including `kind`, `path`, and `cascade`. These keys control fundamental page identity and structure; allowing them in cascades would create ambiguity about which page properties are inheritable versus intrinsic, potentially causing circular dependencies or invalid page states. ### How does Hugo handle multiple date fields in frontmatter? Hugo's `FrontMatterHandler` processes dates through configurable fallback chains defined in `FrontmatterConfig`. For example, the `Date` field defaults to checking `date`, then `pubDate`, then `lastmod`. When `NewFrontmatterHandler` creates date handlers via `createHandlers`, it resolves the first available date from the chain and stores it both in the page's date fields and as a parameter via `setParamIfNotSet`. ### What happens during the two-pass cascade application process? The first pass in `CompileEarly` applies cascades without site filtering to establish base parameters and build the initial site matrix. The second pass then evaluates site-specific cascades that include `sites.matrix` targets. If any site-specific cascade modifies the matrix, Hugo rebuilds it using `buildSitesMatrixFromSitesConfig`, ensuring that multi-site configurations inherit parameters correctly while respecting site boundaries.