From 1a9dc69bd0c2f425673ad3ca088b5b8cd947f004 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 17 Jan 2025 17:06:00 +0100
Subject: [PATCH] chore: tidy templates, add comments

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 layouts/_default/search.html            |  8 ++++++++
 layouts/index.metadata.json             |  2 +-
 layouts/index.redirects.json            | 22 ++++++++++++++++++++++
 layouts/index.robots.txt                |  6 ++++++
 layouts/partials/github-links.html      |  5 +++++
 layouts/partials/head.html              | 11 -----------
 layouts/partials/meta.html              |  9 ++++-----
 layouts/partials/pagemeta.html          |  7 +++++++
 layouts/partials/search-bar.html        |  8 ++++++++
 layouts/partials/sidebar/guides.html    |  8 ++++++++
 layouts/partials/sidebar/mainnav.html   |  6 ++++++
 layouts/partials/sidebar/sections.html  |  8 ++++++++
 layouts/partials/sidebar/tags.html      |  5 +++++
 layouts/partials/tooltip.html           |  4 ++++
 layouts/partials/utils/css.html         |  5 +++++
 layouts/partials/utils/description.html |  6 ++++++
 layouts/partials/utils/keywords.html    |  6 ++++++
 layouts/partials/utils/title.html       | 17 -----------------
 layouts/sitemap.xml                     |  5 +++++
 tailwind.config.js                      |  6 ------
 20 files changed, 114 insertions(+), 40 deletions(-)
 delete mode 100644 layouts/partials/utils/title.html

diff --git a/layouts/_default/search.html b/layouts/_default/search.html
index 1f9a03e168ab..f4e70cfe061f 100644
--- a/layouts/_default/search.html
+++ b/layouts/_default/search.html
@@ -35,6 +35,14 @@ <h1 class="py-4">{{ .Title }}</h1>
     window.addEventListener("load", async function () {
       // Hydrate pagefind
       pagefind = await import("/pagefind/pagefind.js");
+      await pagefind.options({
+        ranking: {
+          termFrequency: 0.2,
+          pageLength: 0.75,
+          termSaturation: 1.4,
+          termSimilarity: 6.0,
+        },
+      });
 
       // Get the query parameter from the URL
       const urlParams = new URLSearchParams(window.location.search);
diff --git a/layouts/index.metadata.json b/layouts/index.metadata.json
index e3426bb18d26..acfaf21f2b80 100644
--- a/layouts/index.metadata.json
+++ b/layouts/index.metadata.json
@@ -1,6 +1,6 @@
 [
 {{- range where site.Pages "Params.sitemap" "!=" false -}}
-  {{- $title := partialCached "utils/title.html" . . -}}
+  {{- $title := .LinkTitle -}}
   {{- $desc := partialCached "utils/description.html" . . -}}
   {{- $kwd := partialCached "utils/keywords.html" . . -}}
   {{- $tags := slice -}}
diff --git a/layouts/index.redirects.json b/layouts/index.redirects.json
index 5add5074019b..6229dfc8d185 100644
--- a/layouts/index.redirects.json
+++ b/layouts/index.redirects.json
@@ -1,3 +1,25 @@
+{{- /*
+
+  This template generates the redirects.json file used to generate 301
+  redirects in production. It takes all the redirects defined in
+  data/redirects.yml, as well as all the aliases defined in front matter, and
+  outputs a simple key-value JSON file:
+
+  {
+    "<request-path>": "<redirect-path>",
+    ...
+  }
+
+  e.g.
+
+  {
+    "/engine/reference/builder/": "/reference/dockerfile/",
+    ...
+  }
+
+  */
+-}}
+
 {{- $redirects := newScratch }}
 {{- range $i, $e := site.AllPages -}} 
   {{- if .Params.aliases -}}
diff --git a/layouts/index.robots.txt b/layouts/index.robots.txt
index d3590928c9e8..3e9a658fdf96 100644
--- a/layouts/index.robots.txt
+++ b/layouts/index.robots.txt
@@ -1,3 +1,9 @@
+{{- /*
+	For Netlify deployments, we disallow all routes to prevent search
+	engines from indexing our preview sites.
+	*/
+-}}
+
 {{- if hugo.IsProduction -}}
 User-agent: *
 
diff --git a/layouts/partials/github-links.html b/layouts/partials/github-links.html
index 75ce8d543290..1f7e518b7393 100644
--- a/layouts/partials/github-links.html
+++ b/layouts/partials/github-links.html
@@ -1,3 +1,8 @@
+{{- /*
+  Adds links for editing the page or requesting changes:
+  - "Edit this page": Only in production, skips files from `_vendor/` (upstream repositories).
+  - "Request changes": Links to a pre-filled issue form.
+*/ -}}
 {{ if hugo.IsProduction }}
 {{ with .File }}
 {{ if not (in .Filename "/_vendor/") }}
diff --git a/layouts/partials/head.html b/layouts/partials/head.html
index cadc04249b8e..0edada5a576b 100644
--- a/layouts/partials/head.html
+++ b/layouts/partials/head.html
@@ -1,16 +1,5 @@
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
-<script type="module">
-const pagefind = await import("/pagefind/pagefind.js");
-await pagefind.options({
-  ranking: {
-    termFrequency: 0.2,
-    pageLength: 0.75,
-    termSaturation: 1.4,
-    termSimilarity: 6.0,
-  },
-});
-</script>
 {{ partial "meta.html" . }}
 {{- if hugo.IsProduction -}}
   <script
diff --git a/layouts/partials/meta.html b/layouts/partials/meta.html
index d89f7391f9aa..56692711320e 100644
--- a/layouts/partials/meta.html
+++ b/layouts/partials/meta.html
@@ -1,10 +1,9 @@
-{{ $title := partial "utils/title.html" . }}
 {{ $description := partial "utils/description.html" . }}
 {{ if .IsHome }}
   <title>{{ site.Title }}</title>
 {{ else }}
   <title>
-    {{ printf "%s | %s" $title site.Title }}
+    {{ printf "%s | %s" .LinkTitle site.Title }}
   </title>
 {{ end }}
 {{ if or (eq .Params.sitemap false) (not hugo.IsProduction) }}
@@ -22,7 +21,7 @@
 <meta name="theme-color" content="#2496ed" />
 
 <!-- SEO -->
-<meta name="twitter:title" itemprop="title name" content="{{ $title }}" />
+<meta name="twitter:title" itemprop="title name" content="{{ .LinkTitle }}" />
 <meta
   name="twitter:description"
   property="og:description"
@@ -38,7 +37,7 @@
   content="{{ (resources.Get "images/thumbnail.webp").Permalink }}"
 />
 <meta name="twitter:image:alt" content="Docker Documentation" />
-<meta property="og:title" content="{{ $title }}" />
+<meta property="og:title" content="{{ .LinkTitle }}" />
 <meta property="og:description" content="{{ $description }}" />
 <meta property="og:type" content="website" />
 <meta
@@ -59,4 +58,4 @@
   itemprop="datePublished"
   content="{{ .PublishDate | default .Lastmod }}"
 />
-  <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebPage","headline":{{ $title | jsonify }},"description":{{ $description | jsonify }},"url":"{{ .Permalink }}"}</script>
+  <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebPage","headline":{{ .LinkTitle | jsonify }},"description":{{ $description | jsonify }},"url":"{{ .Permalink }}"}</script>
diff --git a/layouts/partials/pagemeta.html b/layouts/partials/pagemeta.html
index f799522409eb..426897e23e74 100644
--- a/layouts/partials/pagemeta.html
+++ b/layouts/partials/pagemeta.html
@@ -1,3 +1,10 @@
+{{- /*
+  Renders a table of contents (ToC) for the page.
+  - Uses `.Fragments.Headings` to generate a nested ToC if headings exist and `notoc` is not set to `true`.
+  - Limits heading levels to a min and max range (`$min` and `$max`).
+  - Wraps the ToC in a `data-pagefind-ignore` container to exclude it from search indexing.
+  - Includes a recursive template (`walkHeadingFragments`) to handle nested headings.
+*/ -}}
 {{- $toc := false }}
 {{- with .Fragments }}
   {{- $toc = and (ne page.Params.notoc true) .Headings }}
diff --git a/layouts/partials/search-bar.html b/layouts/partials/search-bar.html
index 72da1f4e5c0e..6595e32d3ff7 100644
--- a/layouts/partials/search-bar.html
+++ b/layouts/partials/search-bar.html
@@ -43,6 +43,14 @@
   <script type="module">
     window.addEventListener("load", async function () {
       const pagefind = await import("/pagefind/pagefind.js");
+      await pagefind.options({
+        ranking: {
+          termFrequency: 0.2,
+          pageLength: 0.75,
+          termSaturation: 1.4,
+          termSimilarity: 6.0,
+        },
+      });
 
       const searchBarInput = document.querySelector("#search-bar-input");
       const searchBarResults = document.querySelector(
diff --git a/layouts/partials/sidebar/guides.html b/layouts/partials/sidebar/guides.html
index 18a40510f1ce..6a51b3474d2a 100644
--- a/layouts/partials/sidebar/guides.html
+++ b/layouts/partials/sidebar/guides.html
@@ -1,3 +1,11 @@
+{{- /*
+  Renders a sidebar for pages in the `/guides` section.
+  - Detects if the current page is part of a multipage guide (`.Store.Set "multipage"`).
+  - Displays the section's title, summary, languages, tags, and estimated time (`Params.time`).
+  - Includes a stepper navigation (`guides-stepper.html`) for multipage guides.
+  - Optionally lists resource links from `Params.resource_links`.
+  - Provides a link back to the main `/guides/` index.
+*/ -}}
 <div class="flex flex-col gap-4 px-4 pt-2">
   {{- $root := . }}
   {{- .Store.Set "multipage" false }}
diff --git a/layouts/partials/sidebar/mainnav.html b/layouts/partials/sidebar/mainnav.html
index 8c2ffe35c644..7055a6f79f6e 100644
--- a/layouts/partials/sidebar/mainnav.html
+++ b/layouts/partials/sidebar/mainnav.html
@@ -1,3 +1,9 @@
+{{- /*
+  Complements the section-specific sidebar navigation.
+  - Renders the main navigation for site sections, linking to the current or ancestor section/page.
+  - Uses the `site.Menus.main` configuration to determine primary navigation structure.
+  - Toggles visibility of nested menu items for the main sections.
+*/ -}}
 <!-- Main navigation for the sidebar -->
 <div class="py-2 px-4" x-data="{ expanded: false }">
   <div class="flex w-full items-center justify-between">
diff --git a/layouts/partials/sidebar/sections.html b/layouts/partials/sidebar/sections.html
index d166b61e21a6..168c534f89de 100644
--- a/layouts/partials/sidebar/sections.html
+++ b/layouts/partials/sidebar/sections.html
@@ -1,3 +1,11 @@
+{{- /*
+  This template recursively renders the sidebar navigation, grouping pages by `Params.sidebar.groups`.
+  Highlights:
+  - Supports hierarchical navigation with collapsible sections (`renderList` template).
+  - Dynamically applies current page highlighting and expanded states.
+  - Handles external links via `Params.sidebar.goto` in `renderSingle`.
+  - Requires `Params.sitemap` and `Params.sidebar` for filtering and behavior.
+*/ -}}
 <!-- section tree -->
 <nav class="md:text-sm flex flex-col">
   <div
diff --git a/layouts/partials/sidebar/tags.html b/layouts/partials/sidebar/tags.html
index e4a8ae9c1ce0..fd1e70d0ce8f 100644
--- a/layouts/partials/sidebar/tags.html
+++ b/layouts/partials/sidebar/tags.html
@@ -1,3 +1,8 @@
+{{- /*
+  Renders a flat list of tags for the "tags" taxonomy.
+  - Unlike `sections.html`, this template is based on taxonomy terms, not section pages.
+  - Highlights the current tag page and links to all tag pages.
+*/ -}}
 <ul class="md:text-sm">
   {{- range site.Taxonomies.tags }}
     <li class="pl-4 hover:text-blue-light hover:dark:text-blue-dark
diff --git a/layouts/partials/tooltip.html b/layouts/partials/tooltip.html
index 51020d05718b..5c4cc30be6e7 100644
--- a/layouts/partials/tooltip.html
+++ b/layouts/partials/tooltip.html
@@ -1,3 +1,7 @@
+{{- /*
+  Renders a tooltip component using Floating UI for positioning.
+  See script at `assets/js/src/tooltip.js` for functionality.
+*/ -}}
 <div data-tooltip-wrapper>
   <div data-tooltip-button class="icon-svg flex items-center text-blue-light dark:text-blue-dark">
     {{ partialCached "icon" "help" "help" }}
diff --git a/layouts/partials/utils/css.html b/layouts/partials/utils/css.html
index 88e48d59f633..5278447a177d 100644
--- a/layouts/partials/utils/css.html
+++ b/layouts/partials/utils/css.html
@@ -1,3 +1,8 @@
+{{- /*
+  Processes and links the main CSS file (`assets/css/styles.css`).
+  - Applies PostCSS, minification, fingerprinting, and post-processing in production.
+  - Adds inline CSS to hide injected images in production builds.
+*/ -}}
 {{ $styles := resources.Get "css/styles.css" }}
 {{ $styles = $styles | css.PostCSS }}
 {{ if hugo.IsProduction }}
diff --git a/layouts/partials/utils/description.html b/layouts/partials/utils/description.html
index 41dea9c8f280..fde917161e34 100644
--- a/layouts/partials/utils/description.html
+++ b/layouts/partials/utils/description.html
@@ -1,3 +1,9 @@
+{{- /*
+  Utility template to extract a description for the current page.
+  - Prioritizes `.Description` or falls back to front matter in `site.Data.frontmatter`.
+  - Replaces newlines with spaces and trims trailing spaces.
+  - Designed for reuse via `partial` calls to generate meta descriptions or similar content.
+*/ -}}
 {{ $desc := "" }}
 {{ if .Description }}
   {{ $desc = strings.Replace .Description "\n" " " }}
diff --git a/layouts/partials/utils/keywords.html b/layouts/partials/utils/keywords.html
index 29bfaeece946..bbcfff56b01a 100644
--- a/layouts/partials/utils/keywords.html
+++ b/layouts/partials/utils/keywords.html
@@ -1,3 +1,9 @@
+{{- /*
+  Utility template to extract keywords for the current page.
+  - Uses `.Keywords` if available or falls back to front matter in `site.Data.frontmatter`.
+  - Cleans and trims keywords, joining them into a comma-separated string.
+  - Intended for reuse in meta tags or other keyword-based contexts.
+*/ -}}
 {{ $keywords := "" }}
 {{ if .Keywords }}
   {{ $keywords = collections.Apply .Keywords "strings.Trim" "." ", " }}
diff --git a/layouts/partials/utils/title.html b/layouts/partials/utils/title.html
deleted file mode 100644
index 101b8baf1ff2..000000000000
--- a/layouts/partials/utils/title.html
+++ /dev/null
@@ -1,17 +0,0 @@
-{{ $title := "" }}
-{{ if .LinkTitle }}
-  {{ $title = .LinkTitle }}
-{{ else }}
-  {{ $title = index (findRE `# .*` .RawContent) 0 | strings.TrimLeft "# " }}
-  {{ with .File }}
-    {{ with (index (site.Data.frontmatter) .Path) }}
-      {{ with .title }}
-        {{ $title = . }}
-      {{ end }}
-    {{ end }}
-    {{ if not $title }}
-      {{ $title = strings.ReplaceRE "[-_]" " " .TranslationBaseName }}
-    {{ end }}
-  {{ end }}
-{{ end }}
-{{ return $title }}
diff --git a/layouts/sitemap.xml b/layouts/sitemap.xml
index 3468e5abe192..0c8f565eff16 100644
--- a/layouts/sitemap.xml
+++ b/layouts/sitemap.xml
@@ -1,3 +1,8 @@
+{{- /*
+  Requires the file `static/sitemap.xsl` to exist for the XSL styling to work.
+  If missing, the sitemap will lack the associated styling.
+  */
+-}}
 {{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
 {{ printf "<?xml-stylesheet type=\"text/xsl\" href=\"%s\"?>" (urls.AbsURL "sitemap.xsl") | safeHTML }}
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
diff --git a/tailwind.config.js b/tailwind.config.js
index b02e5903a22b..b71287b50f00 100644
--- a/tailwind.config.js
+++ b/tailwind.config.js
@@ -43,12 +43,6 @@ module.exports = {
           },
         },
       }),
-
-      gridTemplateColumns: {
-        'main-xl': 'minmax(300px, 1fr) minmax(100ch, 1fr) 1fr',
-        'main-lg': '300px minmax(75ch, 2fr) 1fr',
-        'main-md': '250px 1fr',
-      },
     },
 
     // theme values