fix(layouts): migrate reserved page field lookups (#1133)
Hugo v0.169.0 deprecates reserved front matter lookups through
`.Params`. Migrate title, header description, and submenu link-title
lookups to Page methods while preserving explicit-field presence, custom
parameter overrides, and existing home-title and overview-label
fallbacks.
Run fixture builds at info log level so newly introduced deprecations
fail the diagnostics gate before Hugo promotes them to warnings.
* [x] Added feature fixtures and diagnostics tests. No parameters or
shortcodes were added, so no catalogue entry is required.
## Validation
* All 63 tests pass on standard Hugo v0.160.0, v0.169.0, v0.170.0, and
v0.170.1.
* The isolated PR checkout also passes all 63 tests on v0.170.1.
* 37 header and navigation browser tests pass, including mobile,
keyboard, no-JavaScript, and accessibility cases.
* Static checks pass: 32 HTML files and no internal link errors. Feature
registration, Biome, Markdown lint, and commit hooks pass.
The minimum remains Hugo v0.160.0. Rendered fallback behaviour is
asserted by the new fixture.
6 files modified
12 files added
| New file |
| | |
| | | {{- /* |
| | | Return an explicitly set title, description, or linktitle through its Page |
| | | method. Preserve the former templates' empty-field fallbacks and custom |
| | | params overrides, which can differ from the reserved front matter fields. |
| | | Inspect the parameter map with index, not a deprecated .Params.field lookup. |
| | | */ -}} |
| | | {{- $page := .page -}} |
| | | {{- $field := .field -}} |
| | | {{- $value := false -}} |
| | | {{- if collections.IsSet $page.Params $field -}} |
| | | {{- $methods := dict "title" $page.Title "description" $page.Description "linktitle" $page.LinkTitle -}} |
| | | {{- $value = index $methods $field -}} |
| | | {{- $stored := index $page.Params $field -}} |
| | | {{- if ne $stored $value -}} |
| | | {{- $value = $stored -}} |
| | | {{- end -}} |
| | | {{- end -}} |
| | | {{- return $value -}} |
| | |
| | | {{- if .URL }} |
| | | {{- $label := lang.Translate "menuOverview" . | compare.Default .Name }} |
| | | {{- with .Page }} |
| | | {{- with .Params.linktitle }}{{- $label = . }}{{- end }} |
| | | {{- with partials.Include "func/GetExplicitPageField.html" (dict "page" . "field" "linktitle") }}{{- $label = . }}{{- end }} |
| | | {{- end }} |
| | | {{- $current := partials.Include "func/header/GetMenuCurrent.html" (dict "page" $page "entry" .) }} |
| | | <li class="ananke-submenu-item ananke-submenu-overview"> |
| | |
| | | pages) renders a `div`. |
| | | */ -}} |
| | | {{- $context := . -}} |
| | | {{- with .page.Params.description -}} |
| | | {{- with partials.Include "func/GetExplicitPageField.html" (dict "page" .page "field" "description") -}} |
| | | {{- if compare.Eq $context.variant "page" -}} |
| | | <div class="fw1 f5 f3-l white-80 measure-wide-l center lh-copy mt3 mb4"> |
| | | {{ . }} |
| | |
| | | <meta charset="utf-8"> |
| | | <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> |
| | | {{/* NOTE: the Site's title, and if there is a page title, that is set too */}} |
| | | <title>{{ block "title" . }}{{ with .Params.Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title> |
| | | <title>{{ block "title" . }}{{ with partials.Include "func/GetExplicitPageField.html" (dict "page" . "field" "title") }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title> |
| | | <meta name="viewport" content="width=device-width,minimum-scale=1"> |
| | | <meta name="description" content="{{ with .Description }}{{ . }}{{ else }}{{if .IsPage}}{{ .Summary }}{{ else }}{{ with .Site.Params.description }}{{ . }}{{ end }}{{ end }}{{ end }}"> |
| | | {{ hugo.Generator }} |
| | |
| | | </html> |
| | | {{- with (templates.Defer (dict "key" "hooks-collector")) -}} |
| | | {{- partials.Include "func/hooks/collector-dump.html" . }} |
| | | {{ end -}} |
| | | {{ end -}} |
| | |
| | | |
| | | ## Static checks |
| | | |
| | | Unexpected Hugo warnings, deprecations, and path warnings fail the shared fixture build. Two exact warnings are required for the intentionally invalid navigation fixtures (`unknown` and `invalid`); a missing or repeated warning also fails. The deprecated-header mini-site also requires its one expected deprecation warning and tests suppression. Other feature mini-sites allow no warnings. |
| | | Unexpected Hugo warnings, deprecations, and path warnings fail the shared fixture build. Builds run at info log level so that new `INFO deprecated:` messages also fail before Hugo promotes them to warnings. Ordinary info messages are allowed. Two exact warnings are required for the intentionally invalid navigation fixtures (`unknown` and `invalid`); a missing or repeated warning also fails. The deprecated-header mini-site also requires its one expected deprecation warning and tests suppression. Other feature mini-sites allow no warnings. |
| | | |
| | | HTML validation uses `html-validate:standard` for validity rather than formatting preferences. Hugo's built-in `page/1/` redirects omit an explicit body. The gate checks their redirect metadata, supplies the implied body with the DOM parser, and validates the resulting document. Other pages are validated as emitted. |
| | | |
| New file |
| | |
| | | --- |
| | | description: Home description |
| | | --- |
| New file |
| | |
| | | --- |
| | | title: Articles |
| | | linkTitle: All articles |
| | | --- |
| New file |
| | |
| | | --- |
| | | title: Page title |
| | | description: Page description |
| | | featured_image: /header.svg |
| | | params: |
| | | title: Custom title |
| | | description: Custom description |
| | | --- |
| | | |
| | | Custom parameters override the values shown by the former Params lookups. |
| New file |
| | |
| | | --- |
| | | title: Explicit title |
| | | description: Explicit description |
| | | featured_image: /header.svg |
| | | --- |
| | | |
| | | Article content. |
| New file |
| | |
| | | --- |
| | | title: Custom section |
| | | linkTitle: Reserved link title |
| | | params: |
| | | linktitle: Custom overview |
| | | --- |
| New file |
| | |
| | | --- |
| | | title: Custom child |
| | | --- |
| New file |
| | |
| | | --- |
| | | title: Fallback section |
| | | --- |
| New file |
| | |
| | | # Content with no explicit title or description |
| New file |
| | |
| | | baseURL = "https://example.org/" |
| | | title = "Page fields fixture" |
| | | theme = "ananke" |
| | | |
| | | [params.ananke.navigation] |
| | | submenu_mode = "click" |
| | | |
| | | [[menus.main]] |
| | | name = "Articles" |
| | | identifier = "articles" |
| | | pageRef = "/articles" |
| | | weight = 10 |
| | | |
| | | [[menus.main]] |
| | | name = "Explicit fields" |
| | | parent = "articles" |
| | | pageRef = "/articles/explicit" |
| | | |
| | | [[menus.main]] |
| | | name = "Fallback" |
| | | identifier = "fallback" |
| | | pageRef = "/fallback" |
| | | weight = 20 |
| | | |
| | | [[menus.main]] |
| | | name = "Untitled" |
| | | parent = "fallback" |
| | | pageRef = "/fallback/untitled" |
| | | |
| | | [[menus.main]] |
| | | name = "Custom overview" |
| | | identifier = "custom" |
| | | pageRef = "/custom" |
| | | weight = 30 |
| | | |
| | | [[menus.main]] |
| | | name = "Custom child" |
| | | parent = "custom" |
| | | pageRef = "/custom/child" |
| New file |
| | |
| | | import assert from "node:assert/strict"; |
| | | import { readFileSync } from "node:fs"; |
| | | import { dirname, join } from "node:path"; |
| | | import { test } from "node:test"; |
| | | import { fileURLToPath } from "node:url"; |
| | | import { load } from "cheerio"; |
| | | import { buildFixtureSite } from "../../support/prepare-site.mjs"; |
| | | |
| | | const source = dirname(fileURLToPath(import.meta.url)); |
| | | |
| | | test("explicit page fields retain title, description, and overview fallbacks", () => { |
| | | const output = buildFixtureSite({ source }); |
| | | const page = (name) => load(readFileSync(join(output, name), "utf8")); |
| | | const home = page("index.html"); |
| | | assert.equal(home("title").text(), "Page fields fixture"); |
| | | const explicit = page("articles/explicit/index.html"); |
| | | assert.equal( |
| | | explicit("title").text(), |
| | | "Explicit title | Page fields fixture", |
| | | ); |
| | | assert.equal( |
| | | explicit("header .white-80").text().trim(), |
| | | "Explicit description", |
| | | ); |
| | | assert.deepEqual( |
| | | explicit(".ananke-submenu-overview a") |
| | | .map((_, link) => explicit(link).text()) |
| | | .get(), |
| | | ["All articles", "Overview", "Custom overview"], |
| | | ); |
| | | const untitled = page("fallback/untitled/index.html"); |
| | | assert.equal(untitled("title").text(), "Page fields fixture"); |
| | | const custom = page("articles/custom/index.html"); |
| | | assert.equal(custom("title").text(), "Custom title | Page fields fixture"); |
| | | assert.equal(custom("header .white-80").text().trim(), "Custom description"); |
| | | }); |
| New file |
| | |
| | | <svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><title>Header fixture</title><path fill="#333" d="M0 0h1v1H0z"/></svg> |
| | |
| | | "production", |
| | | "--printPathWarnings", |
| | | "--logLevel", |
| | | "warn", |
| | | "info", |
| | | ...(options.config ? ["--config", options.config] : []), |
| | | ], |
| | | { encoding: "utf8" }, |
| | |
| | | export function checkDiagnostics(output, expectedWarnings = []) { |
| | | const warnings = stripVTControlCharacters(output) |
| | | .split("\n") |
| | | .filter((line) => /^(?:WARN|DEPRECATED)\s/.test(line)); |
| | | .filter((line) => |
| | | /^(?:(?:WARN|DEPRECATED)\s|INFO\s+deprecated:)/.test(line), |
| | | ); |
| | | const matches = (line, expected) => { |
| | | const message = line.replace(/^(?:WARN|DEPRECATED)\s+/, ""); |
| | | const message = line.replace( |
| | | /^(?:(?:WARN|DEPRECATED)\s+|INFO\s+deprecated:\s*)/, |
| | | "", |
| | | ); |
| | | return typeof expected === "string" |
| | | ? message === expected |
| | | : expected.test(message); |
| | |
| | | /Unexpected Hugo/, |
| | | ); |
| | | }); |
| | | test("info-level deprecations fail without rejecting normal info messages", () => { |
| | | checkDiagnostics("INFO build completed\n"); |
| | | assert.throws( |
| | | () => checkDiagnostics("INFO deprecated: Use .Title instead.\n"), |
| | | /Unexpected Hugo/, |
| | | ); |
| | | }); |
| | | test("expected diagnostics are required exactly once", () => { |
| | | checkDiagnostics("WARN Intentional warning\n", ["Intentional warning"]); |
| | | assert.throws( |