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