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

Patrick Kollitsch
12 hours ago 03accb90e5884eee38d2175e097a3b89b1d933fb
feat(layouts): deprecate overriding the header partials

Overriding site-header.html, page-header.html, or site-navigation.html
in a site project still works, but prints a deprecation notice. Sites
should use the header hooks and [params.ananke.header] instead. The
override support is removed in v3 (#1120).

The theme versions of these partials set a marker in the page store.
func/header/IncludeChecked.html includes a partial and prints the
notice if the marker is missing, so only sites that override a partial
see it. Hugo prints the notice once per build, and a site can suppress
it with ignoreLogs = ['ananke-deprecated-<partial>'].

func/debug-cli.html gets the `deprecated` severity: it always prints,
whatever the hook verbosity is, in the warning colour with the label
DEPR. With the new `id` parameter, messages are logged with warnidf or
erroridf, so they can be suppressed.

Every place that exists only for this deprecation has a comment in the
format `@deprecated 2.21.0 remove in 3.0.0: <task> (see #1120)`, so
`grep -rn "@deprecated" layouts` finds them all for v3.
9 files modified
1 files added
203 ■■■■■ changed files
layouts/404.html 5 ●●●●● patch | view | raw | blame | history
layouts/_partials/func/debug-cli.html 39 ●●●●● patch | view | raw | blame | history
layouts/_partials/func/header/IncludeChecked.html 30 ●●●●● patch | view | raw | blame | history
layouts/_partials/page-header.html 8 ●●●●● patch | view | raw | blame | history
layouts/_partials/site-header.html 8 ●●●●● patch | view | raw | blame | history
layouts/_partials/site-navigation.html 2 ●●●●● patch | view | raw | blame | history
layouts/baseof.html 3 ●●●●● patch | view | raw | blame | history
layouts/page/single.html 5 ●●●●● patch | view | raw | blame | history
layouts/single.html 3 ●●●●● patch | view | raw | blame | history
scripts/test-hugo-quickstart.ts 100 ●●●●● patch | view | raw | blame | history
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>
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 -}}
layouts/_partials/func/header/IncludeChecked.html
New file
@@ -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 -}}
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 }}
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 }}
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.
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" .) -}}
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 */}}
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" }}
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> {