mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git

Patrick Kollitsch
18 hours ago f57627951304b21dbd807185b08b8ae2da040f45
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
159 ■■■■■ changed files
layouts/_partials/func/GetExplicitPageField.html 18 ●●●●● patch | view | raw | blame | history
layouts/_partials/header/submenu.html 2 ●●●●● patch | view | raw | blame | history
layouts/_partials/hooks/header/description.html 2 ●●●●● patch | view | raw | blame | history
layouts/baseof.html 4 ●●●●● patch | view | raw | blame | history
tests/README.md 2 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/content/_index.md 3 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/content/articles/_index.md 4 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/content/articles/custom.md 10 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/content/articles/explicit.md 7 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/content/custom/_index.md 6 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/content/custom/child.md 3 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/content/fallback/_index.md 3 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/content/fallback/untitled.md 1 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/hugo.toml 39 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/page-fields.test.mjs 36 ●●●●● patch | view | raw | blame | history
tests/fixtures/page-fields/static/header.svg 1 ●●●●● patch | view | raw | blame | history
tests/support/prepare-site.mjs 11 ●●●●● patch | view | raw | blame | history
tests/unit/build-diagnostics.test.mjs 7 ●●●●● patch | view | raw | blame | history
layouts/_partials/func/GetExplicitPageField.html
New file
@@ -0,0 +1,18 @@
{{- /*
  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 -}}
layouts/_partials/header/submenu.html
@@ -16,7 +16,7 @@
  {{- 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">
layouts/_partials/hooks/header/description.html
@@ -6,7 +6,7 @@
  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">
      {{ . }}
layouts/baseof.html
@@ -4,7 +4,7 @@
    <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 }}
@@ -90,4 +90,4 @@
</html>
{{- with (templates.Defer (dict "key" "hooks-collector")) -}}
  {{- partials.Include "func/hooks/collector-dump.html" . }}
{{ end -}}
{{ end -}}
tests/README.md
@@ -46,7 +46,7 @@
## 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.
tests/fixtures/page-fields/content/_index.md
New file
@@ -0,0 +1,3 @@
---
description: Home description
---
tests/fixtures/page-fields/content/articles/_index.md
New file
@@ -0,0 +1,4 @@
---
title: Articles
linkTitle: All articles
---
tests/fixtures/page-fields/content/articles/custom.md
New file
@@ -0,0 +1,10 @@
---
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.
tests/fixtures/page-fields/content/articles/explicit.md
New file
@@ -0,0 +1,7 @@
---
title: Explicit title
description: Explicit description
featured_image: /header.svg
---
Article content.
tests/fixtures/page-fields/content/custom/_index.md
New file
@@ -0,0 +1,6 @@
---
title: Custom section
linkTitle: Reserved link title
params:
  linktitle: Custom overview
---
tests/fixtures/page-fields/content/custom/child.md
New file
@@ -0,0 +1,3 @@
---
title: Custom child
---
tests/fixtures/page-fields/content/fallback/_index.md
New file
@@ -0,0 +1,3 @@
---
title: Fallback section
---
tests/fixtures/page-fields/content/fallback/untitled.md
New file
@@ -0,0 +1 @@
# Content with no explicit title or description
tests/fixtures/page-fields/hugo.toml
New file
@@ -0,0 +1,39 @@
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"
tests/fixtures/page-fields/page-fields.test.mjs
New file
@@ -0,0 +1,36 @@
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");
});
tests/fixtures/page-fields/static/header.svg
New file
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><title>Header fixture</title><path fill="#333" d="M0 0h1v1H0z"/></svg>
tests/support/prepare-site.mjs
@@ -42,7 +42,7 @@
        "production",
        "--printPathWarnings",
        "--logLevel",
        "warn",
        "info",
        ...(options.config ? ["--config", options.config] : []),
      ],
      { encoding: "utf8" },
@@ -70,9 +70,14 @@
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);
tests/unit/build-diagnostics.test.mjs
@@ -15,6 +15,13 @@
    /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(