From 03accb90e5884eee38d2175e097a3b89b1d933fb Mon Sep 17 00:00:00 2001
From: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com>
Date: Thu, 19 Nov 2026 11:51:55 +0000
Subject: [PATCH] feat(layouts): deprecate overriding the header partials

---
 layouts/_partials/func/header/IncludeChecked.html |   30 +++++++
 layouts/_partials/site-header.html                |    8 +
 scripts/test-hugo-quickstart.ts                   |  100 +++++++++++++++++++++++++
 layouts/_partials/func/debug-cli.html             |   39 +++++++++
 layouts/_partials/page-header.html                |    8 +
 layouts/404.html                                  |    5 +
 layouts/page/single.html                          |    5 +
 layouts/_partials/site-navigation.html            |    2 
 layouts/baseof.html                               |    3 
 layouts/single.html                               |    3 
 10 files changed, 192 insertions(+), 11 deletions(-)

diff --git a/layouts/404.html b/layouts/404.html
index 4e6ca66..32efbae 100644
--- a/layouts/404.html
+++ b/layouts/404.html
@@ -1,4 +1,7 @@
-{{ define "header" }}{{ partials.Include "page-header.html" . }}{{ end }}
+{{ define "header" }}
+  {{/* @deprecated 2.21.0 remove in 3.0.0: include page-header.html directly (see #1120) */ -}}
+  {{ partials.Include "func/header/IncludeChecked.html" (collections.Dictionary "name" "page-header.html" "page" .) }}
+{{ end }}
 {{ define "main" }}
     <article class="center cf pv5 measure-wide-l">
       <h1>
diff --git a/layouts/_partials/func/debug-cli.html b/layouts/_partials/func/debug-cli.html
index acd844d..ecefeea 100644
--- a/layouts/_partials/func/debug-cli.html
+++ b/layouts/_partials/func/debug-cli.html
@@ -14,6 +14,20 @@
 */}}
 
 {{/*
+Parameters:
+
+@param message   string  The message.
+@param severity  string  debug, info, warning, error, or deprecated.
+@param id        string  Optional. Log id. With an id, the message is logged
+                         with fmt.Warnidf or fmt.Erroridf, so a site can
+                         suppress it with `ignoreLogs = ['<id>']`.
+
+The `deprecated` severity is for deprecation notices. It is always printed,
+whatever the verbosity is, in the warning colour with the label DEPR. Hugo
+prints an identical message only once per build.
+*/}}
+
+{{/*
 | Primary | `#AA99FF` | `170, 153, 255` |
 | Ananke  | `#FF80BF` | `255, 128, 191` |
 | Comment | `#708CA9` | `112, 140, 169` |
@@ -39,6 +53,8 @@
   {{- $severity = "error" -}}
 {{- else if compare.Eq $severity "infos" -}}
   {{- $severity = "info" -}}
+{{- else if or (compare.Eq $severity "deprecation") (compare.Eq $severity "depr") -}}
+  {{- $severity = "deprecated" -}}
 {{- end -}}
 
 {{- $verbosity := $config.verbosity | compare.Default "error" -}}
@@ -54,7 +70,9 @@
 {{- end -}}
 
 {{- $shouldOutput := false -}}
-{{- if compare.Eq $verbosity "debug" -}}
+{{- if compare.Eq $severity "deprecated" -}}
+  {{- $shouldOutput = true -}}
+{{- else if compare.Eq $verbosity "debug" -}}
   {{- $shouldOutput = true -}}
 {{- else if and (compare.Eq $verbosity "info") (not (compare.Eq $severity "debug")) -}}
   {{- $shouldOutput = true -}}
@@ -76,12 +94,27 @@
 {{- else if compare.Eq $severity "debug" -}}
   {{- $colourLevel = $colourComment -}}
   {{- $severityLabel = "DEBG" -}}
+{{- else if compare.Eq $severity "deprecated" -}}
+  {{- $colourLevel = $colourWarning -}}
+  {{- $severityLabel = "DEPR" -}}
 {{- end -}}
 
+{{/* Deprecation notices show the whole message in the warning colour. */}}
+{{- $colourMessage := compare.Conditional (compare.Eq $severity "deprecated") $colourWarning $colourComment -}}
+
 {{- if $shouldOutput -}}
+  {{- $line := fmt.Printf "%s%s%s/%s%s %s%s%s" $colourAnanke $namespace $colourComment $colourLevel $severityLabel $colourMessage .message $colourReset -}}
   {{- if compare.Eq $severity "error" -}}
-    {{- fmt.Errorf (fmt.Printf "%s%s%s/%s%s %s%s%s" $colourAnanke $namespace $colourComment $colourLevel $severityLabel $colourComment .message $colourReset) -}}
+    {{- with .id -}}
+      {{- fmt.Erroridf . "%s" $line -}}
+    {{- else -}}
+      {{- fmt.Errorf "%s" $line -}}
+    {{- end -}}
   {{- else -}}
-    {{- fmt.Warnf (fmt.Printf "%s%s%s/%s%s %s%s%s" $colourAnanke $namespace $colourComment $colourLevel $severityLabel $colourComment .message $colourReset) -}}
+    {{- with .id -}}
+      {{- fmt.Warnidf . "%s" $line -}}
+    {{- else -}}
+      {{- fmt.Warnf "%s" $line -}}
+    {{- end -}}
   {{- end -}}
 {{- end -}}
diff --git a/layouts/_partials/func/header/IncludeChecked.html b/layouts/_partials/func/header/IncludeChecked.html
new file mode 100644
index 0000000..41fca56
--- /dev/null
+++ b/layouts/_partials/func/header/IncludeChecked.html
@@ -0,0 +1,30 @@
+{{- /* @deprecated 2.21.0 remove in 3.0.0: remove this check and include the header partials directly (see #1120) */ -}}
+{{- /*
+  Includes a header partial and prints a deprecation notice if the site
+  project overrides it.
+
+  The theme versions of site-header.html, page-header.html, and
+  site-navigation.html set a marker in the page store. If the marker is
+  missing after the include, a site partial replaced the theme partial.
+  Overriding these partials is deprecated: sites should use the header hooks
+  and `[params.ananke.header]`. The notice prints once per build, and a site
+  can suppress it with `ignoreLogs = ['ananke-deprecated-<name>']`.
+
+  @param name  string  The partial: "site-header.html", "page-header.html", or
+                       "site-navigation.html".
+  @param page  page    The current page.
+  @return      HTML    The output of the partial.
+*/ -}}
+{{- $name := .name -}}
+{{- $page := .page -}}
+{{- $key := fmt.Printf "ananke.deprecated.theme-partial.%s" $name -}}
+{{- $page.Store.Delete $key -}}
+{{- $output := partials.Include $name $page -}}
+{{- if not ($page.Store.Get $key) -}}
+  {{- partials.Include "func/debug-cli.html" (collections.Dictionary
+      "severity" "deprecated"
+      "id" (fmt.Printf "ananke-deprecated-%s" (strings.TrimSuffix ".html" $name))
+      "message" (fmt.Printf "Your project overrides layouts/_partials/%s. Overriding the header partials is deprecated and stops working in Ananke v3. Use the header hooks (layouts/_partials/hooks/header/) and [params.ananke.header] instead. See https://github.com/gohugo-ananke/ananke/issues/1120" $name)
+  ) -}}
+{{- end -}}
+{{- return $output -}}
diff --git a/layouts/_partials/page-header.html b/layouts/_partials/page-header.html
index 82f2f96..08b5425 100644
--- a/layouts/_partials/page-header.html
+++ b/layouts/_partials/page-header.html
@@ -1,3 +1,5 @@
+{{- /* @deprecated 2.21.0 remove in 3.0.0: remove this marker, it only detects site overrides of this partial (see #1120) */ -}}
+{{- .Store.Set "ananke.deprecated.theme-partial.page-header.html" true -}}
 {{ $featured_image := partials.Include "func/GetFeaturedImage.html" . }}
 {{ $featured_image_resource := partials.Include "func/GetFeaturedImageResource.html" . }}
 {{ if $featured_image }}
@@ -31,7 +33,8 @@
   {{ end }}
   <header {{ with $responsive_header_id }}id="{{ . }}" {{ end }}class="{{ $featured_image_class }}" style="background-image: url('{{ $background_image }}');">
     <div class="{{ $cover_dimming_class }}">
-      {{ partials.Include "site-navigation.html" . }}
+      {{/* @deprecated 2.21.0 remove in 3.0.0: include site-navigation.html directly (see #1120) */ -}}
+      {{ partials.Include "func/header/IncludeChecked.html" (collections.Dictionary "name" "site-navigation.html" "page" .) }}
       <div class="{{ $header_section_class }}">
         {{ if not .Params.omit_header_text }}
           {{ partials.Include "header/content.html" (collections.Dictionary "page" . "variant" "page" "featured_image" $featured_image) }}
@@ -42,7 +45,8 @@
 {{ else }}
   <header>
     <div class="{{ .Site.Params.background_color_class | compare.Default "bg-black" }}">
-      {{ partials.Include "site-navigation.html" . }}
+      {{/* @deprecated 2.21.0 remove in 3.0.0: include site-navigation.html directly (see #1120) */ -}}
+      {{ partials.Include "func/header/IncludeChecked.html" (collections.Dictionary "name" "site-navigation.html" "page" .) }}
     </div>
   </header>
 {{ end }}
diff --git a/layouts/_partials/site-header.html b/layouts/_partials/site-header.html
index e8d9c17..14a1406 100644
--- a/layouts/_partials/site-header.html
+++ b/layouts/_partials/site-header.html
@@ -1,3 +1,5 @@
+{{- /* @deprecated 2.21.0 remove in 3.0.0: remove this marker, it only detects site overrides of this partial (see #1120) */ -}}
+{{- .Store.Set "ananke.deprecated.theme-partial.site-header.html" true -}}
 {{ $featured_image := partials.Include "func/GetFeaturedImage.html" . }}
 {{ $header := collections.Dictionary "page" . "variant" "site" "featured_image" $featured_image }}
 {{ if $featured_image }}
@@ -7,7 +9,8 @@
   <header class="{{ $featured_image_class }}" style="background-image: url('{{ $featured_image }}');">
     {{ $cover_dimming_class := site.Params.cover_dimming_class | compare.Default "bg-black-60" }}
     <div class="{{ $cover_dimming_class }}">
-      {{ partials.Include "site-navigation.html" .}}
+      {{/* @deprecated 2.21.0 remove in 3.0.0: include site-navigation.html directly (see #1120) */ -}}
+      {{ partials.Include "func/header/IncludeChecked.html" (collections.Dictionary "name" "site-navigation.html" "page" .) }}
       <div class="{{ $header_section_class }}">
         {{ partials.Include "header/content.html" $header }}
       </div>
@@ -16,7 +19,8 @@
 {{ else }}
   <header>
     <div class="pb3-m pb6-l {{ .Site.Params.background_color_class | compare.Default "bg-black" }}">
-      {{ partials.Include "site-navigation.html" . }}
+      {{/* @deprecated 2.21.0 remove in 3.0.0: include site-navigation.html directly (see #1120) */ -}}
+      {{ partials.Include "func/header/IncludeChecked.html" (collections.Dictionary "name" "site-navigation.html" "page" .) }}
       {{ $header_section_class := .Param "header_section_class" | compare.Default "tc-l pv3 ph3 ph4-ns" }}
       <div class="{{ $header_section_class }}">
         {{ partials.Include "header/content.html" $header }}
diff --git a/layouts/_partials/site-navigation.html b/layouts/_partials/site-navigation.html
index 749b9be..095f31e 100644
--- a/layouts/_partials/site-navigation.html
+++ b/layouts/_partials/site-navigation.html
@@ -1,3 +1,5 @@
+{{- /* @deprecated 2.21.0 remove in 3.0.0: remove this marker, it only detects site overrides of this partial (see #1120) */ -}}
+{{- .Store.Set "ananke.deprecated.theme-partial.site-navigation.html" true -}}
 {{- /*
   Site header navigation.
 
diff --git a/layouts/baseof.html b/layouts/baseof.html
index df2021a..805a12c 100644
--- a/layouts/baseof.html
+++ b/layouts/baseof.html
@@ -74,7 +74,8 @@
   <body class="{{ delimit $body_classes " " }}">
     {{- partials.Include "hook.html" (dict "hook" "body-start" "context" .) -}}
     {{- partials.Include "hook.html" (dict "hook" "header-before" "context" .) -}}
-    {{ block "header" . }}{{ partials.Include "site-header.html" .}}{{ end }}
+    {{/* @deprecated 2.21.0 remove in 3.0.0: include site-header.html directly (see #1120) */ -}}
+    {{ block "header" . }}{{ partials.Include "func/header/IncludeChecked.html" (collections.Dictionary "name" "site-header.html" "page" .) }}{{ end }}
     {{- partials.Include "hook.html" (dict "hook" "header-after" "context" .) -}}
     <main class="pb7" role="main">
       {{- partials.Include "hook.html" (dict "hook" "main-before" "context" .) -}}
diff --git a/layouts/page/single.html b/layouts/page/single.html
index 681ec2e..2e7900c 100644
--- a/layouts/page/single.html
+++ b/layouts/page/single.html
@@ -1,4 +1,7 @@
-{{ define "header" }}{{ partials.Include "page-header.html" . }}{{ end }}
+{{ define "header" }}
+  {{/* @deprecated 2.21.0 remove in 3.0.0: include page-header.html directly (see #1120) */ -}}
+  {{ partials.Include "func/header/IncludeChecked.html" (collections.Dictionary "name" "page-header.html" "page" .) }}
+{{ end }}
 {{ define "main" }}
   <div class="flex-l mt2 mw8 center">
     {{/* Calculate a unique class for this page */}}
diff --git a/layouts/single.html b/layouts/single.html
index 8ed434f..4d170e6 100644
--- a/layouts/single.html
+++ b/layouts/single.html
@@ -1,6 +1,7 @@
 {{ define "header" }}
    {{/* We can override any block in the baseof file be defining it in the template */}}
-  {{ partials.Include "page-header.html" . }}
+  {{/* @deprecated 2.21.0 remove in 3.0.0: include page-header.html directly (see #1120) */ -}}
+  {{ partials.Include "func/header/IncludeChecked.html" (collections.Dictionary "name" "page-header.html" "page" .) }}
 {{ end }}
 
 {{ define "main" }}
diff --git a/scripts/test-hugo-quickstart.ts b/scripts/test-hugo-quickstart.ts
index 6981284..608713a 100644
--- a/scripts/test-hugo-quickstart.ts
+++ b/scripts/test-hugo-quickstart.ts
@@ -1634,6 +1634,10 @@
     await assertDateSettings(projectRoot, options.themeName);
     console.log("[OK ] Independent single and summary dates (issue #1112)");
 
+    console.log("\n[RUN] Deprecated header partial overrides (issue #1120)");
+    await assertHeaderDeprecations(projectRoot, options.themeName);
+    console.log("[OK ] Deprecated header partial overrides (issue #1120)");
+
     console.log("\nResult: PASS");
 
     if (options.keepOnSuccess) {
@@ -1671,6 +1675,102 @@
 }
 
 /**
+ * Assert the deprecation notice for overridden header partials (issue #1120).
+ *
+ * Builds the project three times: without an override (no notice), with a
+ * project override of `site-navigation.html` (exactly one notice, and the
+ * override renders), and with that notice in `ignoreLogs` (no notice).
+ *
+ * @param projectRoot Absolute path to the temporary quickstart project.
+ * @param themeName Theme name used in the project configuration.
+ * @throws Error when a notice is missing, repeated, or not suppressible.
+ */
+async function assertHeaderDeprecations(
+  projectRoot: string,
+  themeName: string,
+): Promise<void> {
+  const configPath = join(projectRoot, "hugo.toml");
+  const overrideDir = join(projectRoot, "layouts", "_partials");
+  const overridePath = join(overrideDir, "site-navigation.html");
+  const notice = "ananke/DEPR";
+  const marker = "deprecated-nav-override";
+  const baseConfig = [
+    "baseURL = 'https://example.com/'",
+    "title = 'Ananke Test Quickstart'",
+    `theme = '${themeName}'`,
+  ];
+
+  const build = async (label: string): Promise<string> => {
+    await removePublicDir(projectRoot);
+    const result = await runCommand("hugo", [], projectRoot);
+    if (result.code !== 0) {
+      throw new Error(`Build failed (${label}):\n${result.combined}`);
+    }
+    return result.combined;
+  };
+  const count = (output: string): number => output.split(notice).length - 1;
+  const failures: string[] = [];
+
+  await writeTextFile(configPath, [...baseConfig, ""].join("\n"));
+  const plain = await build("no override");
+  if (count(plain) !== 0) {
+    failures.push("- a build without overrides printed a deprecation notice");
+  }
+
+  await mkdir(overrideDir, { recursive: true });
+  await writeTextFile(overridePath, `<nav class="${marker}">custom</nav>\n`);
+  try {
+    const overridden = await build("site-navigation.html override");
+    if (count(overridden) !== 1) {
+      failures.push(
+        `- expected exactly 1 deprecation notice for the override, got ${count(overridden)}`,
+      );
+    }
+    if (
+      !overridden.includes("overrides layouts/_partials/site-navigation.html")
+    ) {
+      failures.push("- the notice did not name site-navigation.html");
+    }
+    if (!overridden.includes("ananke-deprecated-site-navigation")) {
+      failures.push("- the notice did not show its ignoreLogs id");
+    }
+    const homepage = await readTextFile(
+      join(projectRoot, "public", "index.html"),
+    );
+    if (!homepage.includes(marker)) {
+      failures.push(
+        "- the project override of site-navigation.html did not render",
+      );
+    }
+
+    await writeTextFile(
+      configPath,
+      [
+        "ignoreLogs = ['ananke-deprecated-site-navigation']",
+        ...baseConfig,
+        "",
+      ].join("\n"),
+    );
+    const suppressed = await build("override with ignoreLogs");
+    if (count(suppressed) !== 0) {
+      failures.push("- ignoreLogs did not suppress the deprecation notice");
+    }
+  } finally {
+    await rm(overridePath, { force: true });
+  }
+
+  if (failures.length > 0) {
+    throw new Error(
+      [
+        "Strict assertion failed: header deprecation notices did not behave as expected.",
+        "Failed assertions:",
+        ...failures,
+      ].join("\n"),
+    );
+  }
+}
+
+/**
  * Main entry point.
  */
 async function main(): Promise<void> {

--
Gitblit v1.10.0